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 a workflow or context pack 5 credits
epismo_pack_search Search workflow/context packs 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

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.

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 1 credit
epismo_alias_list List your personal and active-workspace aliases 1 credit
epismo_alias_delete Delete an alias 1 credit

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

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