Get Started

MCP server

Use Epismo tools and resources from MCP clients, including setup, auth, sessions, and tool behavior.

The Epismo MCP server exposes pack and track operations as Model Context Protocol tools. AI clients can read reusable context from packs, then create or update task and goal tracks when work becomes actionable. The server also exposes context resources for the current user, projects, users, and agents so clients can choose the right IDs and scopes before mutating data.

When to use MCP

Use MCP when an AI client should operate Epismo directly.

Goal Why MCP fits
Let an agent find reusable context packs It can call epismo_pack_search and epismo_pack_get
Let an agent break a plan into tasks It can create multiple tracks with epismo_track_apply
Let ChatGPT or Claude read team context OAuth and resources preserve user/workspace context
Let an agent update a workflow pack Pack update tools use PATCH semantics

Use the HTTP API for backend integrations, the CLI for local and CI workflows, and MCP for direct agent-client access.

Server identity and transport

  • Server name: epismo-mcp
  • Transport endpoint: POST / for Streamable HTTP JSON-RPC
  • Session close: DELETE /
  • Health checks: GET /health, GET /healthz
  • OAuth protected resource metadata: GET /.well-known/oauth-protected-resource
  • OAuth authorization server metadata: GET /.well-known/oauth-authorization-server

Authentication

MCP clients authenticate with Authorization: Bearer <oauth_access_token>. The token must include the mcp scope. Server metadata advertises mcp and offline_access, allowing clients to refresh access tokens without forcing sign-in every time.

The client setup flow is:

  1. Register the Epismo MCP server URL in your MCP client.
  2. Complete OAuth and grant the mcp scope.
  3. Send the MCP initialize request.
  4. Store the returned session ID.
  5. Read resources before calling mutation tools.

Sessions

The first request is MCP initialize. The server returns an Mcp-Session-Id header and expects the client to send that header on later requests in the same session. Use DELETE / to close a session.

curl -i https://mcp.epismo.ai/ \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "authorization: Bearer $EPISMO_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0.1.0"}}}'

Resources

Read resources before choosing IDs for tool calls.

URI Contents
epismo://context/current_user Current user/account/workspace JSON
epismo://context/projects Projects accessible in the selected workspace
epismo://context/users Workspace users visible to the caller
epismo://context/agents Installed agents available for assignment

Task assignees can use user IDs or agent IDs. Workflow pack step assignees use human or agent IDs only.

See Resources for payload examples and access field rules.

Pack tools

Tool Purpose Cost
epismo_pack_create Create workflows or contexts 5 credits
epismo_pack_search Search workflows orcontexts 5 credits
epismo_pack_get Read outline, selected nested content, or full content 1 credit
epismo_pack_update Patch a pack by UUID, alias, share URL, or hub URL 1 credit
epismo_pack_like Like or unlike a pack 1 credit
epismo_pack_delete Delete a pack and aliases you own that point to it 1 credit

For large packs, start with epismo_pack_get in outline mode. Use contentIndex.stepIds or contentIndex.blockIds from the response to fetch only the nested content the agent needs. Use full=true only when the client truly needs the entire pack.

See Tools for example tool arguments.

Track tools

Tool Purpose Cost
epismo_track_search Search tasks/goals with filters 2 credits
epismo_track_create Create a task or goal 1 credit
epismo_track_update Patch a task or goal by UUID/URL 1 credit
epismo_track_get Read one track 1 credit
epismo_track_apply Bulk create/update/delete tracks 1 credit
epismo_track_delete Delete a track 1 credit
epismo_track_review Generate a review AI token usage

When an agent plans multiple tasks, epismo_track_apply is usually the best tool. Non-UUID ids let the agent express dependencies within the same call.

When an agent is exploring, narrow filters first and fetch detail only for tracks that matter.

Use epismo_track_review after a task is done or a goal is completed/postponed to generate a read-only review from one or more targets, related tracks, logs, and source packs. Detailed reviews consume credits based on the underlying AI token usage.

Log tools

Tool Purpose Cost
epismo_log_create Append a log/comment to a track free
epismo_log_list List logs — for one track, or across every track 1 credit
epismo_log_delete Delete one log free

Logs attach activity, comments, and review notes to tracks without changing the track's own fields.

Credit behavior

Tool costs are listed in the tables above. Credits are consumed from the current personal/workspace context resolved by the OAuth token. If the context does not have enough credits, the tool call may fail with a credit/payment error.

Alias tools

Tool Purpose Cost
epismo_alias_upsert Create or repoint an alias for a pack you own 5 credits
epismo_alias_get Resolve a single alias to its pack 1 credit
epismo_alias_list List your personal and active-workspace aliases 2 credits
epismo_alias_delete Delete an alias 1 credit

Aliases point to packs only. Tracks are referenced by UUID or URLs containing a UUID.

Suggestion tools

Tool Purpose Cost
epismo_suggestion_create Send an improvement suggestion to a pack owner 5 credits
epismo_suggestion_get Read one suggestion, optionally with the snapshot 1 credit
epismo_suggestion_list List submitted, received, or per-pack suggestions 2 credits
epismo_suggestion_update Update your own suggestion 1 credit
epismo_suggestion_resolve Set the status on a suggestion you own 1 credit

Suggestions are text-first improvement proposals for packs. Anyone who can read a pack can create one; only the author can update it, and only the pack owner can resolve it. See Tools for parameters.

Scopes and sharing

MCP mutation tools use the same access model as the API.

{ "scope": { "type": "personal" } }
{ "scope": { "type": "projects", "ids": ["project-id"] } }

Search tools accept scopes, an array of personal/project scopes. Mutation tools accept sharedWith with userIds and emails. On update, omitted access fields preserve the existing record's access settings.

In this section