Connections

MCP servers

Model Context Protocol — a standard JSON-RPC interface that any service can expose. The agent talks to MCP servers as if their tools were native. Plug in Linear, the Anthropic-published servers, your own internal MCP service, or anything from the public MCP catalog.

// loadAgentDir picks up mcp-servers.json automatically.
// Or set explicitly on the SpecInput:
const spec = await an.specs.push({
  key: 'support',
  instructions: '…',
  mcpServers: [
    { name: 'linear', url: 'https://mcp.linear.app/sse', transport: 'sse' },
    {
      name: 'jira',
      url: 'https://mcp.example.com',
      headers: { Authorization: 'Bearer {{secrets.JIRA_MCP_TOKEN}}' },
    },
  ],
});

What you get

• The runtime connects at session start, lists every tool the server advertises, and registers them as <server-name>__<tool> on the agent's surface.
• Header values can reference workspace secrets with {{secrets.NAME}} — the runtime substitutes the decrypted value at connect time. The secret name never leaves the workspace.
• HTTP and SSE transports are both supported. Stdio is not — the runtime can't spawn subprocesses.

Manage MCP servers on a running agent

Adding / removing MCP servers without re-pushing the whole spec from scratch — useful for CI scripts, multi-tenant onboarding, or letting end users connect their own provider.

await an.agents.addMcpServer(agentId, {
  name: 'linear',
  url: 'https://mcp.linear.app/sse',
  transport: 'sse',
  headers: {
    Authorization: 'Bearer {{secrets.LINEAR_API_KEY}}',
  },
});

Console UI: the same operations are available in the Connections tab on any agent's workspace pane — provider catalog with quick-add cards for Linear, GitHub, the Anthropic catalog, plus a Custom URL escape hatch for everything else.

End-to-end example

A runnable script at packages/kit/examples/mcp-grounded.ts configures an agent, creates a secret with a Linear API token, adds the Linear MCP server, and lists what's wired. Run with:

AGENTNAVA_API_KEY=…  LINEAR_API_KEY=lin_api_…  bun run examples/mcp-grounded.ts

Declarative HTTP tools

For APIs that don't speak MCP. You describe the request shape in JSON; the runtime makes the call. Same secret-placeholder syntax as MCP headers, plus path/body substitution from the LLM's structured arguments.

// http-tools.json next to AGENT.md (or pass via httpTools on SpecInput)
[
  {
    "name": "alpaca_get_account",
    "description": "Read the current Alpaca paper-trading account.",
    "method": "GET",
    "urlTemplate": "{{secrets.ALPACA_BASE_URL}}/v2/account",
    "headers": {
      "APCA-API-KEY-ID":     "{{secrets.ALPACA_KEY_ID}}",
      "APCA-API-SECRET-KEY": "{{secrets.ALPACA_SECRET}}"
    }
  },
  {
    "name": "alpaca_get_recent_bars",
    "description": "Daily bars for a symbol.",
    "method": "GET",
    "urlTemplate": "{{secrets.ALPACA_BASE_URL}}/v2/stocks/{{params.symbol}}/bars",
    "params": {
      "symbol":    { "type": "string", "required": true },
      "timeframe": { "type": "string", "enum": ["1Day", "1Hour"] }
    },
    "headers": { /* … */ }
  }
]

The LLM sees these as named tools with typed arguments — no boilerplate on your side. See the spec.httpTools field reference for the full shape (auth styles, timeouts, JSON body templates).

Which to use