Add an MCP Server#

OSPREY supports two ways to add MCP servers:

  • Declared in the build profile — wire in an external server, written in any language, with an mcp_servers: block. No Python code required.

  • Framework server — create a Python package under src/osprey/mcp_server/ with full access to the framework’s utilities, hooks, and permissions system.

Add an External Server (Profile-Only)#

Declare the server in the deployment’s profile.yml, under the top-level mcp_servers: key:

mcp_servers:
  my-server:
    command: "npx"
    args: ["-y", "@my-org/my-mcp-server"]
    env:
      MY_API_KEY: "${MY_API_KEY}"

  my-python-server:
    command: "{current_python_env}"
    args: ["-m", "my_package.server"]
    env:
      OSPREY_CONFIG: "{project_root}/build/config.yml"

Each entry needs a command — or, for a server that is already running somewhere, a url instead; the two are mutually exclusive. args and env are optional. {project_root} is expanded to the project directory at build time, and {current_python_env} to the project’s own Python interpreter — the one the framework’s servers run under. ${VAR} is left alone for the shell or the container to resolve at run time. A Python module launched with -m has to be importable by that interpreter: either declare its package under the profile’s dependencies: so it is installed into the project venv, or ship it in the profile’s mcp_servers/ directory and reach it with PYTHONPATH: "{project_root}/build/_mcp_servers" (see MCP server injection).

To set permissions on a server, name its tools:

mcp_servers:
  my-server:
    command: "npx"
    args: ["-y", "@my-org/my-mcp-server"]
    permissions:
      allow: [safe_tool, read_data]
      ask: [write_data, delete_item]

Then rebuild:

osprey build

The build records the block in the project’s rendered config.yml (under claude_code.servers) and renders it from there into .mcp.json, which is what launches the server, and into .claude/settings.json, where a server named my-server with allow: [safe_tool] becomes the permission entry mcp__my-server__safe_tool.

Warning

Declare the server in profile.yml, not in the rendered config.yml. profile.yml is the only durable edit surface: every osprey build re-renders config.yml, .mcp.json and .claude/settings.json from it, so a server written straight into claude_code.servers in the rendered file is gone the next time you build. (claude_code.servers.* is a protected key family for that reason — the setup tools and the web terminal’s config panel refuse to write it.)

To turn off a framework-provided server you do not need, use the profile’s config: overlay — a framework server has no mcp_servers: entry of its own to edit:

config:
  claude_code.servers.ariel.enabled: false

Note

An mcp_servers: entry also takes hooks: and writes:. hooks: {pre_tool_use: [<preset>, ...]} attaches a hook preset (such as approval) to every tool of the server. writes: lists the server’s write tools by bare name; the build gates each one with the writes-check and approval hooks, and a read-only run blocks them. A key the entry does not define is ignored with a warning that names the release from which it is refused.

One preset is narrower than attaching it to a whole server suggests: limits validates only channel_write-shaped input — a call carrying a channel/value pair, or an operations list. It abstains on any other shape (denying would deny the server’s reads), so a tool that writes in another shape is not limits-checked. The build says so in a warning when a server attaches it.

Every key an mcp_servers: entry accepts — the remote url and transport forms, the port shorthand, the placeholder rules, and how to ship the server’s own Python package inside the profile so the launch command finds it — is in MCP server injection.

Create Your Own Framework Server#

A framework server is a Python package inside Osprey itself, with access to the shared startup helpers, workspace singletons and hook presets. Writing one is developer work rather than configuration: see Extending Osprey for the base pieces, the registry entry that switches it on, and the test that pins it.