> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# mcp

> Run Clay as a local MCP server over stdio for an MCP host to spawn.

Run Clay as a local Model Context Protocol (MCP) server over stdio. An MCP host — Claude Code, Cursor, or Claude Desktop — spawns this process and the server forwards tool calls to Clay, authenticated with the credentials from [`clay login`](/cli/reference/login) (or the `CLAY_API_KEY` environment variable). It is not meant to be run by hand.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay mcp
```

## Behavior

This command is a long-running MCP server, not a request/response command. It speaks the Model Context Protocol (JSON-RPC) on stdout and runs until the host disconnects (stdin closes). It does not emit the usual JSON success envelope. Failures that occur before the server starts still use the standard error envelope on stderr with a non-zero exit code.

Configure a host to spawn it — no API key is written into the host config; the server uses the credential from `clay login` or `CLAY_API_KEY`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "clay": { "command": "clay", "args": ["mcp"] }
  }
}
```

## Switching workspaces

The connection is pinned to whichever workspace the stored credential was scoped to when the server started (see [`clay login`](/cli/reference/login) for how to switch it). Re-running `clay login` only updates the credential on disk — this MCP server already loaded the old one and keeps using it, so the host must restart or respawn it before the new workspace takes effect.

## Errors

These occur before the server starts; once running, the server communicates over MCP instead.

| Code            | Exit | Notes                                                                                     |
| --------------- | ---- | ----------------------------------------------------------------------------------------- |
| `auth_required` | 3    | No credential available. Run [`clay login`](/cli/reference/login), or set `CLAY_API_KEY`. |
| `auth_invalid`  | 3    | Clay rejected the stored credential. Run [`clay login`](/cli/reference/login) again.      |
| `network_error` | 5    | Could not reach Clay to establish the MCP connection.                                     |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay mcp
```