Embassy (MCP Base)

Embassy (called MCP Bases in the app) is a single server (cmd/mcpbase) running beside a project on the customer's network. It converts OpenAPI-described HTTP APIs into tools at POST /mcp. Optional runner mode executes assigned agents locally using a local OpenAI-compatible model such as Ollama, or a configured cloud provider. Reports wait locally for operator approval; by default, no report reaches the platform without approval.

Flow

sequenceDiagram
    autonumber
    participant P as Agent Tale platform
    participant E as Embassy (customer network)
    participant A as Project API
    participant O as Operator (TUI)
    P->>P: Register MCP Base
    P->>E: Check (initialize + tools/list)
    P->>P: Assign agent (prompt copy, cron, max turns)
    E->>P: GET /api/v1/embassy/sync (API key)
    P-->>E: Assignments with prompt copies
    E->>A: Model tool-use execution
    E->>E: Save report (pending_approval)
    O->>E: approve_report (POST /admin/mcp)
    E->>P: POST /api/v1/embassy/reports (approved only)
    P-->>E: Accept with duplicate detection

Setup

The static binary is in services/mcpbase-service/cmd/mcpbase, with Dockerfile at services/mcpbase-service/Dockerfile. No database is required. Runner state uses STATE_DIR/assignments.json and reports/<uid>.json, which operators can inspect and back up. GET /health returns project name and tool count.

Basic

tools/list derives operations from the spec; tools/call proxies the upstream with a 256 KiB response limit.

Discovery (optional)

Use PATHFINDER_DOCKER, PATHFINDER_DOCKER_HOST, PATHFINDER_DOCKER_HOST_GATEWAY, PATHFINDER_SCAN_CIDRS (your network only), PATHFINDER_SCAN_PORTS, PATHFINDER_PROJECT_DIR, PATHFINDER_ALLOW_CIDRS, PATHFINDER_CONCURRENCY (default 32). Legacy DISCOVER_* names remain supported, with PATHFINDER_* taking precedence.

When enabled, pathfinder_discover (formerly discover_services) scans Docker containers, project spec files and allowed ranges. POST /api/v1/mcp-bases/:id/discover returns candidates only; it does not register them automatically.

Runner (optional)

All three PLATFORM_* values are required to start the runner. Otherwise Embassy opens no platform connection and serves only /mcp and /health.

Create PLATFORM_API_KEY as the MCP Base's owner. The web dialog does not list these scopes; use authenticated POST /api/v1/user/api-keys with {"name":"...","scopes":["read:assignments","submit:report"]}. The first reporting key binds to the base; reports from another key are rejected.

Platform side

Web: Settings → Developer → MCP Bridge → Go to MCP Bases → (/settings/projects). TUI: MCP Bases, with n new, s assignments, p reports and l local approval.

Assignment

• Assign only agents you own or purchased. Web takes agent ID and optional cron.
• Prompt is copied as prompt v1. Later agent edits do not change it. Explicit PUT /api/v1/mcp-bases/:id/assignments/:aid with resync_prompt: true updates it and increments the version.
• Schedule: five-field cron, no seconds, UTC. Blank means manual-only. Invalid cron is rejected.
• Max turns: default five, maximum 20. Web uses the default; API can override.
• With Lore connected, sync prepends context. Delivered summaries enter agent memory; full reports, including tool calls, enter Lore documents.

Case runs

Select 2–5 registered Embassies. The platform introspects each and analyzes with an LLM asynchronously, charging your wallet.

Optional on-chain attestation anchors the output hash of successful Case runs only. It never blocks the run and requires chain configuration.

Approval flow

stateDiagram-v2
    [*] --> pending_approval: Run completes
    pending_approval --> approved: approve_report
    pending_approval --> rejected: reject_report
    approved --> delivering: outbox
    delivering --> delivered: Platform accepts
    delivering --> dead: 12 attempts or 4xx
    dead --> approved: retry_report

• pending_approval, rejected and dead are local-only. The platform sees delivered reports only.
• Approval uses the separate POST /admin/mcp MCP server with MCP_ADMIN_TOKEN. Its tools are hidden from platform introspection and the local model.
• Connect TUI with --embassy-url http://<embassy>:8090/admin/mcp --embassy-token <MCP_ADMIN_TOKEN>, AGENT_TALE_EMBASSY_URL / AGENT_TALE_EMBASSY_TOKEN, or config.toml [[embassies]]. Multiple Embassies show a selector first.

Delivery: the outbox retries exponentially from 30 seconds to 30 minutes, with ±20% jitter. After 12 attempts (about 2.5 hours) it becomes dead. Platform 4xx goes directly to dead, except 409 (already exists), which counts as delivered. Report IDs make retries idempotent. Every transition persists to disk for crash recovery. Platform limits: summary 8 KiB, output 256 KiB, up to 50 tool calls (64 KiB).

Current capabilities and limits

Related pages

Toolsets · Connectors · API keys · Lore