Connections

Connect OAuth apps

Open Connections after signing in to create a workspace connection, or open an agent's Build → Connections tab to create an agent-scoped connection. Enabled deployments can offer Microsoft Outlook, Teams, SharePoint, OneDrive, Gmail, Google Calendar, Google Drive, Slack, HubSpot, and Notion through self-hosted Nango Connect. The catalog marks connectors that have not yet passed that deployment's rollout gate as coming soon.

1. Select an app and finish its authorization flow.
2. AgentNava adds its reviewed read and search tools for that app.
3. Ask the agent to use the connected data, for example: What are my latest emails? or Find the latest proposal in Drive.

AgentNava stores only an encrypted Nango connection reference. Provider access and refresh tokens remain in the self-hosted Nango database. At runtime, AgentNava-owned tools call the open-source Nango Proxy; Nango MCP and Nango Functions are not used. An agent-scoped connection takes precedence over the workspace connection.

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, since 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, a 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