@geostack/arc-mcp-adapter

MCP transport adapter for Arc. It exposes your Arc-protected actions as MCP tools and routes every tool call back through Arc policy, approvals, signed execution, and audit.

MCP answers "what tools can the agent call?" Arc answers "should this specific action run right now?" This adapter is the bridge. It never executes app business logic, never approves actions, and never bypasses policy.

Install

npm install @geostack/arc-mcp-adapter

What it does

• Authenticates to Arc with ARC_AGENT_TOKEN
• Fetches Arc action definitions for your app (ARC_APP_SLUG or ARC_APP_ID)
• Maps each Arc action to an MCP tool (same name, Arc input schema, risk level + default decision in the description)
• Creates an Arc invocation for every MCP tool call and returns allowed / pending-approval / blocked
• Fails closed when config is missing or Arc is unavailable; redacts token-like strings from returned errors

Configure

export ARC_API_URL=https://your-arc-api
export ARC_AGENT_TOKEN=<agent-token>   # from a secret store; never commit
export ARC_APP_SLUG=<app-slug>         # or ARC_APP_ID

Run (stdio MCP server)

arc-mcp-adapter config    # print sanitized config
arc-mcp-adapter start     # start the MCP stdio server

Example MCP client entry:

{
  "mcpServers": {
    "arc": {
      "command": "arc-mcp-adapter",
      "args": ["start"],
      "env": {
        "ARC_API_URL": "https://your-arc-api",
        "ARC_AGENT_TOKEN": "<agent-token>",
        "ARC_APP_SLUG": "<app-slug>"
      }
    }
  }
}

Decision behavior

• allow — Arc returns the invocation (typically queued for signed execution). The adapter never fakes execution.
• ask — returns "requires approval in Arc." A human approves through the Arc approval flow; the adapter never auto-approves and never converts ask to allow.
• block — terminal. The adapter returns blocked and never calls app handlers.

Idempotency is preserved: pass _meta.arc_idempotency_key (or _meta["arc/idempotency-key"]), otherwise the adapter generates one. Arc audit remains the system of record.

See the Arc package for the full action-authority model.

License

MIT