MCP Servers

Overview

MCP servers give Claude Code extra capabilities during sessions — like accessing databases, calling external APIs, or working with specialized tools. Configure them once in Open Poet, and they're automatically available in every session.

Configuring MCP Servers

Add MCP servers through the Open Poet UI or the API:

Go to Settings > MCP Servers.
Click Add Server.
Provide the server configuration:

Field	Description
`name`	Display name for the MCP server
`command`	Executable command to start the server (e.g., `npx`, `python`)
`args`	JSON array of command arguments
`env`	JSON object of environment variables to pass to the server process
`enabled`	Whether the server is active

Example: Add a filesystem MCP server

curl -X POST http://localhost:8080/api/config/mcps \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
    "env": {},
    "enabled": true
  }'

Session Injection

When you start a Claude Code session, all enabled MCP servers are automatically loaded and available to the AI. No manual configuration is needed per session.

Open Poet also provides its own built-in tools (prefixed with openpoet_) that give the AI the ability to manage your projects, tasks, and skills during sessions.

Tool Policies

Control which MCP tools Claude Code can use through the tool policy system:

Policy Modes

Mode	Behavior
`allow_all`	All tools are permitted. Only the denied list restricts specific tools.
`deny_all`	No tools by default. Only the allowed list permits specific tools.
`custom`	Uses both allowed and denied lists for fine-grained control.

Policy Levels

Global policy — applies to all projects by default. Configure at /api/config/tool-policies.
Project policy — overrides the global policy for a specific project. Configure at /api/projects/{id}/tool-policy.

If a project has no specific policy set, it inherits the global policy.

Context-Based Defaults

Context	Default Policy
`session`	`deny_all` — full Claude Code sessions require explicit tool allowlisting
`chat`	`allow_all` — AI chat panel allows all tools by default
`http`	`allow_all` — HTTP transport allows all tools by default

HTTP Transport (Advanced)

By default, MCP servers communicate with Claude Code automatically. If you need to expose MCP tools over HTTP for external integrations, start Open Poet with:

Enable HTTP MCP transport

openpoet -mcp-http

This makes MCP tools available at the /mcp endpoint. Most users will not need this.

Built-in MCP Tools

Open Poet injects its own MCP server with the openpoet_ prefix. These tools let the AI manage your projects during sessions:

Tool	Description
`openpoet_list_skills`	List available skills
`openpoet_create_skill`	Create a new skill
`openpoet_update_skill`	Update an existing skill
`openpoet_delete_skill`	Delete a skill
`openpoet_list_projects`	List all projects
`openpoet_list_mcp_servers`	List MCP server configurations
`openpoet_create_mcp_server`	Add a new MCP server
`openpoet_update_mcp_server`	Update MCP server config
`openpoet_delete_mcp_server`	Remove an MCP server
`openpoet_update_settings`	Update application settings
`openpoet_sync_all`	Sync config to all projects
`openpoet_list_project_files`	List files in a project
`openpoet_read_project_file`	Read a file from a project
`openpoet_get_memory_doc`	Get project memory document
`openpoet_execute_tool`	Execute a tool from another MCP server