Pencil MCP Server

Pencil exposes its agent/operator tools through MCP so clients can work with Pencil tasks, comments, files, repos, roadmap objects, products, ideas, iterations, builds, and connector state without carrying Pencil internals or vendor credentials directly.

There are two MCP connection paths:

Hosted remote MCP at SITE_URL/api/mcp, authenticated with OAuth or an explicitly MCP-enabled Pencil API key.
Local stdio MCP through pencil-gateway mcp, authenticated with the paired local gateway device token.

Local stdio still works exactly as before:

pencil-gateway pair
pencil-gateway mcp

Pairing stores a device token in ~/.pencil/gateway.json. The local MCP server reads that token, fetches the current tool catalog from Pencil, and forwards tool calls back to Pencil with Authorization: Bearer <device token>.

Local vs remote MCP

The official MCP remote-server model describes internet-hosted servers that clients connect to by URL, often through Claude Custom Connectors. Pencil supports that model at:

https://your-pencil-host.example.com/api/mcp

Client or deployment	Status	How to connect
Claude Desktop and other local MCP clients	Supported in v1	Configure the `pencil-gateway` command with `args: ["mcp"]`.
Self-hosted Pencil	Supported in v1	Set `PENCIL_MC_URL` before `pencil-gateway pair` and `pencil-gateway mcp`.
Claude web Custom Connector / hosted remote MCP	Supported	Use `SITE_URL/api/mcp` and OAuth.
MCP clients with static bearer headers	Supported	Create an API key in Settings with MCP access enabled and send `Authorization: Bearer pk_live_...`.

Hosted remote MCP

Use OAuth whenever the MCP client supports connector-style auth. Pencil publishes protected-resource metadata and OAuth authorization-server metadata for discovery, supports dynamic client registration, PKCE authorization-code flow, refresh-token rotation, and token revocation.

For clients that support static headers, org admins can go to Settings -> API Keys, create a key, and enable MCP access. Existing API keys are REST-only unless MCP is explicitly enabled.

POST /api/mcp
Authorization: Bearer pk_live_...
Content-Type: application/json

Read API keys receive mcp:read and can list/call read-only remote MCP tools. Write API keys receive mcp:read mcp:write and can call safe write tools. API keys do not receive offline_access; they are long-lived bearer secrets with optional expiry.

Local client config

Point a local MCP client at the gateway binary:

{
  "mcpServers": {
    "pencil": {
      "command": "pencil-gateway",
      "args": ["mcp"]
    }
  }
}

For self-hosted Pencil, set PENCIL_MC_URL before pairing and before starting the MCP server:

PENCIL_MC_URL=https://your-pencil.example.com pencil-gateway pair
PENCIL_MC_URL=https://your-pencil.example.com pencil-gateway mcp

Capabilities

Pencil v1 exposes MCP tools. It does not expose MCP resources or prompts yet.

MCP capability	Pencil v1 status	Notes
Tools	Supported	Remote MCP discovers tools through `tools/list`; local gateway discovers through `GET /api/mc/tools` and calls through `POST /api/mc/actions`.
Resources	Planned	Good candidates include task context, saved output summaries, repo status snapshots, connector sync state, and workspace/project context.
Prompts	Planned	Good candidates include task handoff, project summary, repo proposal review, and connector sync workflows.

What it can do

The MCP server exposes tools from the same catalog Pencil uses internally. Local MCP includes non-sandbox agent tools plus high-value gateway actions:

Tasks and agents: list, create, assign, status updates, questions, comments, revive, nudge, submit plans, soft delete, restore.
Content: list/create content, update content stages, ask content questions.
Files and memory: save output, save diffs, record lessons, record memories, recall memories.
Chat and feedback: post chat replies, task comments, and feedback comments.
Repos: resolve local-gateway repo credentials, report status/branches, propose changes, mark proposals merged or closed.
Builds: record project builds and deployments.
Roadmap/product work: goals, initiatives, epics, products, components, features, requirements, personas, stakeholders, and links between them.
Ideas and iterations: create/list/update/restore/delete ideas and iterations, promote ideas to features, attach/detach tasks.

Hosted remote MCP applies a stricter safety filter: it excludes sandbox, omitted, credential-bearing, local-gateway-only, destructive, and dangerous tools. Read-scoped remote tokens also exclude write tools. MCP clients should treat tools/list as the runtime source of truth.

Tool permissions

Pencil and the MCP client each have a permission layer:

Pencil-side exposure controls whether a tool is exposed, gated, internal-only, or intentionally omitted from MCP.
Client-side permissions decide which listed tools the MCP client is allowed to call in a given conversation or connector configuration.

Recommended starting sets:

Workflow	Enable these tools first
Review task context	`list_tasks`, `get_task`, `list_project_tasks`, `list_agents`, `recall_memory`
Comment or hand off work	`post_comment`, `save_output`, `submit_plan`, `ask_question`
Repo proposal workflow	Local gateway: `get_repo_credentials`, `report_repo_status`, `report_repo_branches`, `propose_repo_change`. Remote MCP: `report_repo_status`, `report_repo_branches`, `propose_repo_change`.
Product and roadmap work	`list_products`, `get_product_full`, `list_features`, `create_feature`, `update_feature`, `create_requirement`
Ideas and iterations	`list_ideas`, `create_idea`, `promote_idea_to_feature`, `list_iterations`, `attach_task_to_iteration`

Keep destructive or credential-bearing tools disabled unless the current workflow needs them.

MCP vs REST API vs internal runtime

Use MCP when an agent or operator wants a named Pencil action: update a task, save a deliverable, post a chat reply, or invoke connector-aware work. Credential-bearing repo operations are local-gateway-only.

Use the REST API when an external service needs structured CRUD over Pencil resources with an API key. REST is stable public integration surface; MCP is the agent-friendly command surface.

Use the internal Anthropic runtime tools when Pencil-managed agents are executing inside Pencil. Those tools share the same catalog, but also include task-scoped sandbox tools that are not part of local MCP v1.

Security model

MCP clients do not receive org-scoped connector tokens such as Notion, Slack, or GitHub tokens. Those stay inside Pencil. Credential-bearing operations, such as get_repo_credentials, are only exposed through the paired local gateway bearer path, and Pencil still applies server-side workspace and task-assignment checks.

Hosted remote MCP accepts either an OAuth access token or an explicitly MCP-enabled API key. OAuth tokens are bound to the canonical SITE_URL/api/mcp resource. API keys validate through the same hashed-key path as REST keys, but must have MCP access enabled. Pencil injects the authorized workspace server-side and ignores caller-supplied orgId or workspaceId.

Treat ~/.pencil/gateway.json and pk_live_... API keys like private keys. Revoke unused or lost devices from Pencil settings, revoke stale API keys from Settings -> API Keys, remove OAuth MCP connector grants you no longer use, and only enable the tools needed for the current client or workflow.

Dangerous tools are hidden by default. Bulk destructive tools and hard roadmap deletes appear only when both are true:

PENCIL_MCP_ENABLE_DANGEROUS_TOOLS=1
pencil-gateway mcp --include-dangerous

Internal-only tools are not exposed through local MCP:

record_usage is billing/usage telemetry.
run_shell, read_file, write_file, and list_dir are task-sandbox tools for Pencil-managed Anthropic runtimes.

Troubleshooting

Symptom	What to check
No Pencil tools appear	Run `pencil-gateway doctor`, confirm `~/.pencil/gateway.json` exists, and restart the MCP client after pairing.
The client reports 401 or revoked token	Re-pair with `pencil-gateway pair` or revoke the old device in Pencil settings and pair again.
Hosted remote MCP returns 401	Confirm the client is using OAuth for `SITE_URL/api/mcp`, or that the bearer key is a current `pk_live_...` key.
Hosted remote MCP returns 403	Confirm the API key was created with MCP access, or that the OAuth/API-key scope includes `mcp:write` for write tools.
Self-hosted tools point at the wrong Pencil instance	Set the same `PENCIL_MC_URL` before both pairing and running `pencil-gateway mcp`.
Dangerous tools are missing	Confirm the Pencil server enables `PENCIL_MCP_ENABLE_DANGEROUS_TOOLS=1` and start the gateway with `--include-dangerous`.
A tool call fails after listing successfully	Check the upstream `/api/mc/actions` error. Pencil may be rejecting the task, workspace, assignment, or credential scope server-side.
A remote client cannot send static headers	Use OAuth; static `Authorization` headers are only for clients that support them.

Examples

List in-progress tasks:

{
  "name": "list_tasks",
  "arguments": { "status": "in_progress" }
}

Post a task comment:

{
  "name": "post_comment",
  "arguments": {
    "agentId": "agent_123",
    "taskId": "task_123",
    "content": "**Update**\n- Tests are passing."
  }
}

Save a deliverable:

{
  "name": "save_output",
  "arguments": {
    "agentId": "agent_123",
    "taskId": "task_123",
    "name": "audit.md",
    "content": "# Audit\n\nFindings..."
  }
}

Propose a repo change after pushing a branch:

{
  "name": "propose_repo_change",
  "arguments": {
    "agentId": "agent_123",
    "repoId": "repo_123",
    "taskId": "task_123",
    "branch": "agent/orion/mc-123-fix-login",
    "targetBranch": "main",
    "title": "Fix login redirect",
    "summary": "Updates the redirect guard and adds a regression test."
  }
}

Connector tools

Connector-specific MCP tools should follow the same rule: Pencil owns org-scoped connector credentials and exposes narrow tools. The Notion Ideas connector documents planned tools for sync status, push, pull, link, and import; those are not exposed in v1 until the connector runtime implements them.