Skip to main content
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 (or the CLAY_API_KEY environment variable). It is not meant to be run by hand. 
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: 
{
  "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 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.
CodeExitNotes
auth_required3No credential available. Run clay login, or set CLAY_API_KEY.
auth_invalid3Clay rejected the stored credential. Run clay login again.
network_error5Could not reach Clay to establish the MCP connection.

​
Examples

clay mcp