Let an External Agent In

Create a headless agent or register an MCP agent with tenant-scoped credentials.

This page is optional for headless integrations.

Goal: give an external agent a tenant-scoped credential while keeping it behind RobotMoney's authentication, policy, and audit controls.

Choose the Agent Path

Use POST /v1/agents for headless HTTP agents that need to request authorization decisions. The owner session receives a one-time brain_ak_ key, and the agent exchanges it at /token for a five-minute JWT with payment_intent:propose.

Use POST /v1/execution/agents/register for MCP agents that need the MCP tool surface and on-chain scope attestation.

Create a Headless Agent

const agent = await brain.agents.create({
  kind: "tenant",
  name: "Vendor Assistant",
  purpose: "Request authorization decisions before using customer-owned rails.",
  autonomy_preset: "ask_always",
});

console.log(agent.agent.id, agent.api_key_once, agent.exchange.token_endpoint);

Store api_key_once once, exchange it for an access token, and call POST /v1/authorizations with execution: "external". The agent can receive an approved, needs-review, or blocked decision. It cannot execute money.

Register an MCP Agent

The MCP registration route requires an agent identifier, role, and display name. The SDK calls that route.

const agent = await brain.agents.register({
  agent_id: "ag_vendor_assistant",
  role: "vendor_management",
  display_name: "Vendor Assistant",
  scope_hash: "0x...",
  onchain_address: "0x...",
  registered_tx: "0x...",
});

console.log(agent.id, agent.registered_tx);

The optional scope_hash, onchain_address, and registered_tx fields are the only optional registration fields in the current public request shape.

Available Agent Scopes

A headless tenant agent uses payment_intent:propose for authorization decisions and never receives execute scope.

An MCP agent can hold these canonical scopes: ledger:read, wiki:read, raw:read, raw:write, payment_intent:propose, and execution:propose. There is no public SDK grantScope or revoke method today. Scope issuance for MCP agents is controlled by the registered-agent flow.

External agents can propose but cannot execute money movement. Execution remains inside the PaymentIntent lifecycle and passes the section 6 gate.

Connect to MCP

The MCP server shares the API host. Production and staging use these endpoints:

POST https://api.robotmoney.com/v1/agents/mcp
POST https://staging-api.robotmoney.com/v1/agents/mcp

The agent authenticates with its tenant-scoped JWT. Tool discovery returns only the tools the principal's scopes allow.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Ask a Grounded Question

The authenticated JWT supplies the tenant. Do not include a tenant identifier in the tool arguments.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wiki.question",
    "arguments": {
      "question": "What invoices are overdue?",
      "max_evidence_depth": 3
    }
  }
}

wiki.question accepts question, optional as_of, and optional max_evidence_depth.

Review Agent Activity

const page = await brain.audit.list({
  actor: "agent:ag_vendor_assistant",
  since: "2025-09-01T00:00:00.000Z",
  limit: 100,
});

for (const event of page.events) {
  console.log(event.action, event.created_at);
}

Halt and Restore a Registered Agent

The current SDK exposes operational controls rather than per-scope mutation.

await brain.agents.halt("ag_vendor_assistant");
await brain.agents.restore("ag_vendor_assistant");

Both operations require payment_intent:approve. Restoring an agent does not resume payment intents paused by its earlier halt.

What's Next

• MCP Server Overview

• Audit Every Action