Skip to Content
GuidesMCP Server

MCP Server

shep mcp runs a Model Context Protocol  server over stdio. Register it with an MCP client (Claude Code, Cursor, Claude Desktop, VS Code, …) and that client’s agent can list and create features, start them, watch what Shep’s agents are doing, approve or reject gates, and answer agent questions.

The server works on the same local database as the rest of Shep (~/.shep, or $SHEP_HOME). Features it creates show up in the web UI, shep tui and shep feat ls like any other.

Register the server

Claude Code

claude mcp add shep -- shep mcp

Any MCP client

Most clients take a JSON entry like this (Claude Desktop’s claude_desktop_config.json, Cursor’s mcp.json, and similar):

{ "mcpServers": { "shep": { "command": "shep", "args": ["mcp"] } } }

The client starts shep mcp itself; you don’t run it in a terminal. If the client can’t find shep, use the full path from which shep.

shep mcp --log-level <debug|info|warn|error> sets how much the server logs (default warn). Logs go to stderr, so they never mix with the protocol on stdout.

Settings → MCP in the web UI shows the command to register and the full tool list.

Settings → MCP tool catalog showing the Agent activity, Repositories & settings and Task management tool groups

Tools

The server exposes 22 tools.

Features

ToolWhat it does
list_featuresList features, optionally filtered by lifecycle status (Pending, Implementation, Review, …)
show_featureOne feature’s details. Takes a full id or an id prefix
create_featureCreate a feature from a description (userInput) in a repository (repositoryPath). Optional name, description, and pending: true to create it without starting an agent. Uses your workflow defaults
start_featureStart a pending feature. Returns the run id right away

Agent activity

ToolWhat it does
get_agent_activityWhat each feature’s agent is doing: working, blocked, waiting, done or failed, with the reason, any open question, and a version number. Lists active features, or one by id. Filter with repositoryPath; includeSettled adds finished ones
wait_for_agent_activityWait until a feature reaches one of the given states (default blocked, done or failed) and return it. Returns at once if it already matches. timeoutMs defaults to 60 seconds, at most 10 minutes
decide_feature_gateApprove a feature waiting at an approval gate, or reject it with feedback the agent iterates on
answer_agent_questionAnswer the open question a feature’s agent asked

See Agent activity for what each state and reason means.

Agent runs

ToolWhat it does
run_agentRun a named agent with a prompt. Returns the run id right away
show_agent_runStatus and details of a run
list_agent_runsAll runs, most recent first
stop_agent_runStop a running agent

Repositories and settings

ToolWhat it does
list_repositoriesRepositories Shep tracks
get_settingsCurrent settings (models, agent, environment, workflow, …)
update_settingsReplace settings with the object you pass. Send the full settings object (start from get_settings)

Projects and work items

ToolWhat it does
list_projectsProjects and their ids
list_work_itemsWork items in a project, with filters
get_work_itemOne work item, by UUID or by key such as PROJ-42
create_work_itemCreate a work item in a project
update_work_itemChange a work item’s fields
delete_work_itemDelete a work item

Chat

ToolWhat it does
post_chat_blockShow a rich block in a Shep chat conversation: spec_review (markdown to approve or send back), plan_card (a plan to implement or refine) or html_preview (a self-contained HTML page in a sandboxed frame). scope is global, repo-<id>, app-<id> or a feature id

Example: delegate a feature and wait for it

Ask the agent in your MCP client something like “Create a Shep feature in /work/acme to add a login page, then tell me when it needs me.” It will typically call:

  1. create_feature with userInput and repositoryPath.
  2. wait_for_agent_activity with the new feature id, calling again after each timeout.
  3. get_agent_activity to read why the feature is blocked.
  4. decide_feature_gate or answer_agent_question, once you tell it what to do.

Questions from Shep’s own agents: ask_decision

The other direction also uses MCP. When a feature runs in the background, Shep can give its agent a private, per-run MCP server with exactly one tool, ask_decision. An agent that is truly blocked on a choice it can’t make itself calls it with 2–9 options and exactly one marked as recommended.

The question goes to your agent-questions inbox, the feature drawer and your notifications. The agent waits for your answer. If nobody answers before the deadline, it proceeds with its recommended option, and the activity log says so. The default deadline is 30 minutes; change it in Settings → Workflow → Question deadline. An agent can ask for a different deadline, up to 24 hours.

ask_decision is only given to runs whose agent accepts a per-run MCP configuration (today, Claude Code), and only while the Agent Collaboration & Supervision flag (collaboration, on by default) is on. The per-run server has no other Shep tools, so a run can’t start or stop agents through it.

See Decisions & agent questions for the full model.

What’s next