Build on Chief — MCP server, REST API, and CLI

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 using the Chief MCP tools to list the files uploaded to a project — Claude Code calling Chief over MCP — one prompt, your real files.

Install

Homebrew is the recommended install on macOS:

brew install --cask Storytell-ai/tap/chief-mcp

go install github.com/Storytell-ai/chief-mcp@latest

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:

Flag	Environment variable	Required
`--api-key`	`CHIEF_API_KEY`	yes
`--project`	`CHIEF_PROJECT_ID`	for project-scoped tools
`--base-url`	`CHIEF_BASE_URL`	no (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.

Resource	Tools
Chats	`create_chat`, `list_chats`, `get_chat`, `update_chat`, `delete_chat`, `send_message`, `list_messages`, `get_message`, `delete_message`
Assets	`upload_file`, `list_assets`, `get_asset`, `update_asset`, `delete_asset`
Labels	`create_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`

What you can ask it

Once the server is connected you drive it in plain language — your agent picks the right tools and chains them. The tools above map to requests like:

“What did we decide about pricing in the last few chats?” — the agent calls list_chats and get_chat to read recent conversations, then answers from them.
“Upload every PDF in this folder and tag them contracts.” — upload_file per file, then create_label and attach_label.
“Summarize the most recent live session.” — list_sessions, then get_session.
“Create an action that emails me a summary of new assets every morning.” — create_action with a schedule.
“Remember that I always want answers in metric units.” — create_memory.

Because the agent decides which tools to call, the exact sequence varies from run to run — the same request can resolve through different tools and still be correct. Give it the goal (“find and summarize…”), not a tool name, and let it plan the calls. A server only sees the project it is scoped to, so to work against a different project, point it there with CHIEF_PROJECT_ID.

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

Option	Applies to	Description
`--api-key`	stdio	Chief API key (env `CHIEF_API_KEY`)
`--project`	both	Default project id (env `CHIEF_PROJECT_ID`)
`--base-url`	both	API base URL (env `CHIEF_BASE_URL`)
`--insecure`	both	Skip TLS verification (local dev only)
`--debug`	both	Dump HTTP requests and responses
`--addr`	http	Address to listen on (default `:8080`)
`--path`	http	Path 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 — chief mcp config prints a ready-to-paste server snippet with your credentials filled in.

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” — confirm the id exists in the project the server is scoped to (CHIEF_PROJECT_ID). A wrong or missing project id is the usual cause.
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.

​Install

​Credentials

​Security

​Tools

​What you can ask it

​Transports

​Configure a client

​Troubleshooting

Install

Credentials

Security

Tools

What you can ask it

Transports

Configure a client

Troubleshooting