> For the complete documentation index, see [llms.txt](https://docs.robotmoney.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.robotmoney.com/platform/let-an-external-agent-in.md).

# 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

```typescript
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.

```typescript
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.

```json
{
  "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.

```json
{
  "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

```typescript
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.

```typescript
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](/mcp-server/overview.md)
* [Audit Every Action](/platform/audit-every-action.md)