MCP connector

Install the optional SDK peer:

npm install @modelcontextprotocol/sdk

Then define the server and the exact tools the agent may call:

import { mcp } from '@noir-agent/agent/connectors/mcp'

const docs = mcp({
  server: 'internal-docs',
  transport: {
    type: 'http',
    url: 'https://mcp.example.com/mcp',
    headers: { authorization: `Bearer ${process.env.DOCS_MCP_TOKEN}` },
  },
  tools: [{
    name: 'search',
    description: 'Search approved internal documentation.',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string' } },
      required: ['query'],
      additionalProperties: false,
    },
    effect: 'read',
    retry: 'safe',
  }],
})

Why tools are pinned

Noir does not automatically expose every tool advertised by a server. The host pins names, descriptions, schemas, effects, approvals, and retries. This makes schema changes reviewable and keeps the model's authority stable.

Transports

HTTP uses Streamable HTTP with a safe fetch implementation, optional headers, and connection reuse. Stdio starts an explicit command with arguments, environment, and working directory. Do not pass the full host environment to an untrusted stdio server.

Result handling

Structured MCP content is preferred. Text/image content is returned in a bounded envelope when structured content is absent. An MCP isError result becomes a tool failure. Connection failures invalidate the client so a later call can reconnect.

Dynamic connections

The static connector is for host-configured servers. For user-added MCP servers, OAuth, connection records, pinned manifests, and schema-drift checks, use @noir-agent/agent/connections/mcp with the connections capability. Dynamic access must still be scoped to a verified owner.

Close the connector during shutdown so sessions and stdio children do not leak.