# MCP Servers

Build stateless HTTP MCP servers on Ferrite and project application operations as safe tools.

Ferrite apps can expose Model Context Protocol tools over stateless HTTP. A
client initializes, lists tools, and calls a tool without holding an always-on
WebSocket session.

## Add the MCP package

```bash
ferrite add mcp
```

The source package provides the constrained wire format, stateless client,
resource server, and authorization support without adding an async runtime or
second Cargo dependency to your app.

For an application surface, `agent-ready` can project the same operation
declarations into both MCP and OpenAPI:

```bash
ferrite add agent-ready
```

Declare tool names, descriptions, input and output schemas, and read-only or
idempotent traits. Delegate the call to the same domain handler used by HTTP.

## Route the endpoint

```json filename="ferrite.json"
{
  "services": [{ "name": "mcp-requests", "primitive": "queue" }],
  "applications": [{
    "name": "tools",
    "artifact_key": "apps/tools@v1",
    "artifact_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
    "bindings": [
      { "handle": "requests", "kind": "queue", "service": "mcp-requests" }
    ],
    "routes": [{
      "prefix": "/mcp",
      "binding": "requests",
      "kind": "api",
      "forward_headers": ["mcp-protocol-version", "authorization"]
    }]
  }]
}
```

Forward `authorization` only when the MCP surface actually validates a scoped
token. Never expose a browser session cookie to remote MCP.

## Authentication and authorization

Remote MCP tools require explicit delegated scopes. Browser WebMCP can reuse
the current signed-in origin because the tool executes through the app’s normal
session and CSRF boundary. A tool that cannot establish the required subject,
tenant, or role returns a structured authentication requirement instead of
fixtures or an implicit tenant.

## Tool design

- Give each tool one bounded job.
- Describe when to call it and where required IDs come from.
- Mark read-only tools accurately.
- Require idempotency keys for retryable mutations.
- Return structured errors without secrets or internal stack traces.
- Keep user content clearly marked as untrusted data.

See [Agent-native Apps](/developers/agent-native-apps/) for the complete
discovery surface.