Skip to main content
chief-mcp is a Model Context Protocol server for Chief. It lets any MCP client — Claude Code, Claude Desktop, Cursor, or Codex — manage chats, assets, labels, actions, live sessions, skills, and memories directly in your Chief project. It is a single static Go binary built on the Go SDK and talks only to the Chief public REST API. To get started you need three things: a Chief Personal Access Token, the chief-mcp binary (install below), and an MCP client — Claude Code, Claude Desktop, Cursor, Codex, or VS Code.
A Claude Code session calling Chief over MCP to answer a question
Chats, assets, and labels are available now. Actions, skills, memories, and live sessions require the latest Chief API release and are rolling out — their tools are exposed but may return errors until then.

​
Install

Homebrew is the recommended install on macOS: 
brew install --cask Storytell-ai/tap/chief-mcp
go install requires a Go toolchain. Prebuilt binaries for each platform are on the releases page.

​
Credentials

A Chief Personal Access Token is required and sent as the API key. Most tools are project-scoped and also need a project id. Pass credentials as flags or read them from the environment:
FlagEnvironment variableRequired
--api-keyCHIEF_API_KEYyes
--projectCHIEF_PROJECT_IDfor project-scoped tools
--base-urlCHIEF_BASE_URLno (defaults to https://api.storytell.ai)
Create a token in the Chief app under Settings → API tokens — see Introduction for tokens and project ids.

​
Security

  • Treat your Personal Access Token like a password. Pass it through CHIEF_API_KEY rather than committing it into a client config file.
  • A token only reaches the projects it is scoped to. Set CHIEF_PROJECT_ID (or the X-Project-Id header in HTTP mode) to bound the server to one project.
  • --insecure disables TLS verification and is for local development only.

​
Tools

The server exposes 44 tools across seven resources. Chats, assets, and labels work today; the resources marked ⟳ require the latest Chief API release and are rolling out.
ResourceTools
Chatscreate_chat, list_chats, get_chat, update_chat, delete_chat, send_message, list_messages, get_message, delete_message
Assetsupload_file, list_assets, get_asset, update_asset, delete_asset
Labelscreate_label, list_labels, get_label, update_label, delete_label, attach_label, detach_label
Actions ⟳create_action, list_actions, get_action, update_action, delete_action, enable_action, disable_action
Live sessions ⟳list_sessions, get_session, update_session, delete_session
Skills ⟳create_skill, list_skills, get_skill, update_skill, delete_skill, enable_skill, disable_skill
Memories ⟳create_memory, list_memories, get_memory, update_memory, delete_memory

​
Transports

chief-mcp runs as your own process — locally over stdio (the common case) or self-hosted over HTTP. There is no vendor-hosted Chief MCP endpoint; you run the binary. Two transports are selected by subcommand:
  • stdio (default) — for a local agent that launches the binary as a subprocess.
  • http — for remote or web-based agents. Each request authenticates from its headers: the API key as a Bearer token in Authorization (or X-API-Key), and the project in X-Project-Id.
# Local agent (stdio).
chief-mcp stdio

# Remote agent (http) on :8080 at /mcp.
chief-mcp http --addr :8080 --path /mcp
OptionApplies toDescription
--api-keystdioChief API key (env CHIEF_API_KEY)
--projectbothDefault project id (env CHIEF_PROJECT_ID)
--base-urlbothAPI base URL (env CHIEF_BASE_URL)
--insecurebothSkip TLS verification (local dev only)
--debugbothDump HTTP requests and responses
--addrhttpAddress to listen on (default :8080)
--pathhttpPath to mount the endpoint on (default /mcp)
In HTTP mode the server authenticates each request from its headers, so --api-key applies to stdio only. --project sets the default project for requests that omit X-Project-Id.

​
Configure a client

The fastest path is the chief CLI, which writes a ready-to-paste config prefilled with the installed binary path and your credentials. Install the CLI too, then run: 
chief mcp config claude   # Claude Code / Claude Desktop
chief mcp config cursor   # Cursor
chief mcp config codex    # Codex
Only installed chief-mcp? Use the hand-written snippets on MCP clients instead — they need no extra tooling.
chief mcp config claude printing an MCP server JSON snippet
For hand-written config and the full per-client setup, see MCP clients.

​
Troubleshooting

  • Authentication failed — confirm CHIEF_API_KEY is set in the server’s environment (or sent as a header in HTTP mode) and that the token is valid. chief doctor checks credentials and connectivity.
  • A tool returns “not found” or an unexpected error — actions, skills, memories, and live sessions require the latest Chief API release and may not be available yet.
  • The client doesn’t list the server or its tools — restart the client session. MCP servers are launched once and don’t hot-reload after a config change.
  • Inspect the traffic — add --debug to dump every HTTP request and response the server makes.