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 <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
epismo_pack_create Create a workflow or context pack
epismo_pack_update Patch a pack by UUID, alias, share URL, or hub URL
epismo_pack_get Read outline, selected nested content, or full content
epismo_pack_search Search workflow/context packs
epismo_pack_like Like or unlike a pack
epismo_pack_delete Delete a pack and aliases you own that point to it

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.

epismo_pack_search consumes credits. epismo_pack_get is still best used in outline-first mode for large packs so the client only hydrates the content an agent actually needs.

See Tools for example tool arguments.

Track tools

Tool Purpose
epismo_track_create Create a task or goal
epismo_track_update Patch a task or goal by UUID/URL
epismo_track_get Read one track
epismo_track_search Search tasks/goals with filters
epismo_track_apply Bulk create/update/delete tracks
epismo_track_delete Delete a track

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

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

Credit behavior

In MCP, agent usage and search calls consume credits. 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
epismo_alias_upsert Create or repoint an alias for a pack you own
epismo_alias_delete Delete an alias you own

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.

Local development

The monorepo MCP service listens on port 8080 by default.

npm install
npm run mcp:dev

Useful environment variables are MCP_URL, API_URL, WEB_URL, and backend gRPC addresses. Production clients should use the hosted MCP URL rather than local development endpoints.

In this section