# MCP Server

Cortex includes a Model Context Protocol server that exposes chain and indexer state as tools for AI agents.

The MCP server is stdio-based and talks to the Cortex REST API. External testers do not need database access; point `API_URL` at the hosted API.

## Tools

| Tool | Purpose |
|------|---------|
| `lookup_agent` | Look up an agent by ID. |
| `list_open_intents` | List intents filtered by status. |
| `get_policy` | Get policies for a smart account. |
| `explain_tx` | Explain indexed transaction events. |
| `lookup_attestation` | Look up an attestation by ID. |
| `list_solvers` | List registered solvers and fill counters. |
| `list_attestors` | List registered attestors and attestation counters. |
| `preflight_transaction` | Check indexed policies before signing/submitting a transaction. |
| `list_merchants` | List registered merchants by owner or active status. |
| `get_merchant` | Get a merchant profile plus reputation summary. |
| `list_services` | List registered services by merchant, capability, or active status. |
| `get_service` | Get a registered service by numeric service ID. |
| `preflight_purchase` | Check whether a signed-payment policy allows a purchase by merchant, token, facilitator, and amount. |
| `prepare_purchase` | Load service, merchant reputation, purchase preflight, and quote input fields for an agent purchase. |
| `get_reconciliation` | Get quote, receipt, settlement, and signed-payment reconciliation for a quote hash. |
| `prepare_register_merchant` | Return a Base Sepolia transaction payload for `CommerceRegistry.registerMerchant`. |
| `prepare_register_service` | Return a Base Sepolia transaction payload for `CommerceRegistry.registerService`. |
| `prepare_register_agent` | Return a Base Sepolia transaction payload for `AgentRegistry.registerAgent`. |
| `prepare_set_payment_policy` | Return a Base Sepolia transaction payload for `PolicyModule.setPaymentPolicy`. |
| `list_licenses` | List Cortex license inventory for an agent, issuer, merchant, service, or asset. |
| `check_license` | Check whether an agent can use a licensed asset for a requested action and context. |

## Commerce Purchase Tools

For agentic commerce flows, prefer the commerce-specific tools over raw transaction preflight:

1. `list_services` or `get_service` to discover what can be bought.
2. `get_merchant` to inspect merchant status, receipt volume, disputes, and trust signals.
3. `preflight_purchase` to check the agent owner's signed-payment policy before any payment authorization is signed.
4. `prepare_purchase` to return the service, merchant, policy result, and quote fields in one agent-readable response.
5. `get_reconciliation` after a receipt exists to verify quote, receipt, settlement, and policy-payment records match.

`preflight_purchase` accepts either `merchant_id` or a direct merchant payout address. A policy with merchant `0x0000000000000000000000000000000000000000` means "any merchant"; an exact merchant policy overrides the any-merchant policy, so an agent owner can revoke or tighten one merchant even when broad purchasing is enabled.

## Commerce Setup Tools

The `prepare_register_*` and `prepare_set_payment_policy` tools do not hold private keys and do not submit transactions. They return exact `chain_id`, `to`, `value`, and `data` fields that a wallet, smart account, or agent signer can inspect and submit. This keeps setup flows production-safe while still giving an agent enough structure to create merchants, services, agents, and policies without demo scripts.

## Local Usage

Build the server:

```bash
cd mcp
npm run build
```

Run with:

```bash
API_URL=https://cortex-api.projectaegis.ai node dist/src/index.js
```

When configuring an MCP client from the repo root, use:

```json
{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["mcp/dist/src/index.js"],
      "env": {
        "API_URL": "https://cortex-api.projectaegis.ai"
      }
    }
  }
}
```

For local development, set `API_URL=http://localhost:3001` instead.