Pencil MCP Server

Use Pencil from your MCP client to find tasks, read context, and save work. Hosted MCP does not require Pencil Gateway. Install the gateway only when your client needs a local stdio connection or you want to run Pencil-assigned work on your computer.

Choose a connection#

Replace the example host with your Pencil instance. See Pencil Gateway for installation and device pairing. Running pencil-gateway start is not required for an MCP client connection.

Hosted remote MCP#

Add your Pencil instance's /api/mcp URL to your client's remote-server configuration. Choose OAuth when supported, then sign in, select your workspace, and approve access. Pencil supports discovery, dynamic client registration, PKCE, refresh-token rotation, and revocation.

For clients with static headers, organization admins can create a key in Settings → API Keys with MCP access enabled. Existing REST-only keys do not work for MCP.

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

Read keys grant mcp:read; write keys grant mcp:read mcp:write. API keys are long-lived bearer secrets with optional expiry and do not receive offline_access.

Local stdio with OAuth#

After installing the gateway package, run:

pencil-gateway mcp --oauth

The first run opens Pencil for sign-in, workspace selection, and consent. Registration and rotating tokens are stored with user-only permissions in ~/.pencil/mcp-oauth.json. No device pairing is needed.

Configure your stdio client with:

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

Use --account work for a separate profile and --mc-url https://your-pencil.example.com (or PENCIL_MC_URL) for self-hosted Pencil. Include the same flags in the client's args. If consent port 8787 is busy, choose another with --oauth-callback-port <port>.

OAuth stdio proxies the hosted endpoint and follows its workspace, scope, and tool restrictions. It cannot be combined with --include-dangerous.

Local stdio with device pairing#

Complete gateway pairing, then use the config above with "args": ["mcp"]. For a named pairing, use "args": ["mcp", "--account", "work"].

The server reads the selected gateway config, uses its saved Pencil URL and device token, fetches the tool catalog, and forwards calls to Pencil. Workspace and task-access checks still apply server-side.

Task progress and ownership#

update_task_status follows the authenticated caller:

For unassigned work, use review to request confirmation or blocked to record an obstacle. Progress is attributed to the invoking agent in task history without changing assignment. A refused completion returns TASK_UNASSIGNED_REQUIRES_OWNER, allowed statuses, and remedies such as assign_task or update_task_status(status=review). A caller without an agent identity receives TASK_AGENT_REQUIRED with assignment and OAuth alternatives. Completion still checks checklists and review gates.

assign_task can explicitly claim unassigned work, subject to workspace and assignment-readiness checks. autoPickupDisabled only controls automatic pickup of inbox work; progress reports preserve it and do not claim a task. update_task edits metadata and may promote backlog work into inbox when assigning a sprint. set_task_phase changes phase membership and schedules gate release. Neither metadata tool accepts an arbitrary completion status; use update_task_status for that.

Troubleshooting#

Admins can inspect transport, caller, status, and duration in Settings → Integrations → Access Telemetry. Tool arguments and bearer tokens are not recorded.

What to try next#

Read MCP tools and permissions to choose the tools your client can use.