MCP tools and permissions
Tool capabilities, transport boundaries, and permission controls.
Capabilities
Pencil v1 exposes MCP tools. It does not expose MCP resources or prompts yet.
Remote MCP discovers tools through tools/list; paired mode fetches GET /api/mc/tools and calls POST /api/mc/actions.
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, rename, set or clear distinct human-owner and agent assignments, status updates, exact lifecycle-history reads, questions, comments, complete task relationships (parent/sub-task, blocked by/blocking, relates to, duplicate), roadmap relationship updates, revive, nudge, submit plans, soft delete, restore.
- Handoffs: create/list/get/update structured entries and action items through OAuth or a paired gateway with a verified human identity. API keys cannot impersonate a human author.
- Content: list/create/rename content, update content stages, ask content questions.
- Files and memory: save and rename output files, 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, links between them, and queued PRD/FRD generation.
- 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, dangerous, and non-recoverable destructive tools. The single-task delete_task operation is available to write-scoped clients because it only moves the task to trash and can be undone with restore_task; bulk deletion remains excluded. 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_context, list_task_events, list_task_relationships, list_project_tasks, list_agents, recall_memory |
| Comment or hand off work | post_comment, save_output, create_handoff, list_handoffs, get_handoff, update_handoff, create_handoff_action_item, list_handoff_action_items, get_handoff_action_item, update_handoff_action_item |
| 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, generate_prd, list_features, create_feature, update_feature, generate_frd, create_user_story, create_requirement, list_requirements, link_task_relationship, unlink_task_relationship, link_task_epic, link_goal_initiative, link_goal_epic, link_initiative_epic |
| 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 for named Pencil actions, the REST API for resource CRUD, and Pencil-managed runtimes for task-sandbox execution.
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 OAuth tokens are bound to SITE_URL/api/mcp; API keys require MCP access. Pencil injects the authorized workspace server-side.
Protect API keys and local token files. Revoke unused devices, API keys, and OAuth grants in Pencil settings.
Dangerous tools are hidden by default. For paired MCP only, enable PENCIL_MCP_ENABLE_DANGEROUS_TOOLS=1 on the Pencil server and opt in locally:
pencil-gateway mcp --include-dangerous
Internal-only tools are not exposed through local MCP:
record_usageis billing/usage telemetry.run_shell,read_file,write_file, andlist_dirare task-sandbox tools for Pencil-managed Anthropic runtimes.
Connector tools
Pencil owns connector credentials and exposes narrow tools. See the Notion Ideas Connector for planned sync tools; use tools/list to check what is available.
What to try next
Follow MCP task workflows to read task history and save work.