MCP Server

Reference·Claude Desktop · Claude Code

CrewLayer ships a built-in MCP (Model Context Protocol) server that exposes all core features as tools. This means Claude — in Claude Desktop, Claude Code, or any MCP-compatible host — can call CrewLayer directly without you writing any HTTP code.

Transports

The MCP server supports two transports:

stdio — for Claude Desktop and Claude Code (VS Code). The host spawns the process and communicates via stdin/stdout.
SSE — for Docker-based deployments or any HTTP-accessible host. Listens on port 8001 by default.

Claude Desktop

Add the following to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

claude_desktop_config.json

{
  "mcpServers": {
    "crewlayer": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/CrewLayer",
      "env": {
        "CREWLAYER_API_KEY": "crwl_your_key_here",
        "CREWLAYER_BASE_URL": "http://localhost:8000",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Restart Claude Desktop. You'll see the CrewLayer tools appear in the tool picker.

Claude Code (VS Code)

In Claude Code settings (/config → MCP servers), add:

.claude/settings.json

{
  "mcpServers": {
    "crewlayer": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/CrewLayer",
      "env": {
        "CREWLAYER_API_KEY": "crwl_your_key_here",
        "CREWLAYER_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

💡

If CrewLayer is running in Docker, set CREWLAYER_BASE_URL=http://host.docker.internal:8000 (macOS/Windows) or use the container's network IP on Linux.

Docker / SSE Mode

For headless environments or when running behind a reverse proxy, use SSE transport. The MCP server runs alongside the API:

terminal

# Start in SSE mode (listens on :8001)
MCP_TRANSPORT=sse CREWLAYER_API_KEY=crwl_... python -m mcp.server

# Or via Docker (already included in docker-compose.yml)
docker compose up -d mcp

Then point your MCP client to http://localhost:8001/sse.

Available Tools

The MCP server exposes 9 tools. All tool calls are automatically logged to CrewLayer actions (except the agent status tools, which manage status directly).

memory_recall

Search an agent's long-term memories using semantic similarity.

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent
query	string	required	Natural language search query
top_k	int	optional	Max memories to return (default: 10)

memory_append

Append a message to an agent's short-term (Redis) memory for a session.

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent
session_id	string	required	UUID of the active session
role	string	required	`user` \| `assistant` \| `system`
content	string	required	Message text

memory_extract

Close a session and extract long-term memories from its conversation history using Claude.

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent (for action logging)
session_id	string	required	UUID of the session to close and extract from

action_log

Log a tool invocation as an immutable action record.

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent
tool_name	string	required	Name of the tool called
input_params	object	required	Tool input parameters
output_result	object	required	Tool output
status	string	required	`success` \| `error` \| `timeout`
duration_ms	int	optional	Wall-clock execution time
session_id	string	optional	Session this action belongs to

action_list

List recent actions for an agent with optional filters.

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent
tool	string	optional	Filter by tool name
status	string	optional	Filter by status
limit	int	optional	Max results (default: 50)
cursor	string	optional	Pagination cursor

context_write

Write a value to the shared context blackboard.

Parameter	Type	Required	Description
namespace	string	required	Logical grouping (e.g. `pipeline`)
key	string	required	Key within the namespace
value	any	required	Any JSON-serializable value
agent_id	string	optional	For action logging

context_read

Read a value from the shared context blackboard.

Parameter	Type	Required	Description
namespace	string	required	Namespace
key	string	required	Key
agent_id	string	optional	For action logging

agent_status

Get the current runtime status of an agent. Served from Redis cache (TTL 60s).

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent

agent_set_status

Update the runtime status of an agent. This is the only way to change status — the @auto_log decorator intentionally does not touch status.

Parameter	Type	Required	Description
agent_id	string	required	UUID of the agent
status	string	required	`idle` \| `working` \| `error`
session_id	string	optional	Associate with an active session

ℹ️

The @auto_log decorator wraps all tools except agent_status and agent_set_status. It records tool_name, input_params, output_result, and duration_ms to the CrewLayer action log automatically — you don't need to call action_log manually when using the MCP server.

← Previous TypeScript SDK Next → Self-Hosting