Agent Gateway (MCP)

How a proposal flows

1. Propose. The agent calls propose_actionwith a runbook ID and its args. The gateway validates the args, checks the key's runbook allowlist, and stages a pending approval card in your IT admin channel. Nothing has executed.
2. Provenance. A threaded note appears under the card naming the agent's API key and its stated reason, so approvers always know the request came from an agent.
3. Decide. A human approves or denies from Slack, Teams, or the dashboard. A denial changes nothing. There is no autonomous path around the gate.
4. Execute + record. On approval, the runbook runs against your stack and the chain records three linked events: the agent's proposal, the human decision, and the execution outcome. The agent learns the result by polling get_run_status.

Step 1: Create a scoped agent key

In your admin portal under API, create a key with the agent:propose scope. Least privilege applies: this scope can propose and poll, but cannot execute runbooks directly or read audit rows.

• Restrict what the agent may propose by adding rb:<runbook id> scopes (for example rb:RB-001 and rb:RB-002). A key with one or more rb:* scopes can only propose those runbooks. A key with none may propose any gateway-supported runbook.
• Add audit:readonly if the agent should be able to read the org's audit chain through search_audit_events.
• One key per agent. Provenance notes and audit rows carry the key label, so distinct keys keep distinct agents distinguishable, and revocation stays surgical.

Step 2: Connect your MCP client

The gateway is a stateless streamable-HTTP MCP server at POST /api/mcp, authenticated with your key as a bearer header. Claude clients:

# Claude Code (CLI)
claude mcp add --transport http ascendcore https://ascendcore.ai/api/mcp \
  --header "Authorization: Bearer ak_live_YOUR_KEY"

# Claude (web/desktop): Settings -> Connectors -> Add custom connector
#   URL:    https://ascendcore.ai/api/mcp
#   Auth:   Authorization: Bearer ak_live_YOUR_KEY

Microsoft Copilot Studio: add a custom MCP tool/connector pointing at the same URL with an API-key (bearer) authorization header. Any other client that speaks MCP over streamable HTTP works the same way. The raw wire format, if you are building your own client:

POST https://ascendcore.ai/api/mcp
Authorization: Bearer ak_live_YOUR_KEY
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18", "capabilities": {},
              "clientInfo": { "name": "my-agent", "version": "1.0.0" } } }

The tool surface

What a proposal looks like

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "propose_action",
    "arguments": {
      "runbookId": "RB-002",
      "args": { "userEmail": "sarah.chen@acme.com" },
      "reason": "User reported a lost phone in the IT support thread."
    } } }

// Result (the action has NOT run; a human decides in Slack/Teams):
{ "runId": "mfa_1234567890_123456", "status": "pending_approval",
  "runbook": { "id": "RB-002", "name": "MFA Re-enrollment" },
  "note": "Staged for human approval in the organization's admin channel. ..." }

Agent-facing contract, stated in the server's own MCP instructions: never represent an action as performed until get_run_status returns approved.

Error codes you will actually see

Security model

• Propose-only by architecture. No gateway tool executes an integration action. Execution happens only after a human approves, through the same deterministic runbooks that serve chat and API requests.
• No credentials cross the gate. Agents hold an AscendCore API key, never credentials to your identity stack. Keys are salted-hashed at rest, scope-gated, rate-limited, and revocable from the dashboard.
• Provenance approvers can see. Every staged card carries a threaded note naming the agent key and its stated reason. Agent-supplied text is sanitized before it reaches your channel, so an agent cannot inject mentions or links at approvers.
• Audit-chained. The proposal itself is recorded as agent_gateway.proposedon the org's tamper-evident SHA-256 chain, followed by the human decision and the execution outcome, usable as evidence for SOC 2 and ISO 27001 reviews.
• Sandbox-aware. Orgs in Sandbox Mode exercise the full propose-approve flow with mocked execution. Recommended for your first agent.