MCP

Two related surfaces share this page: the mcps catalogue declares the external Model Context Protocol servers an agent can call (plus a per-server tool policy), and the mcp block configures hyprpilot's three in-tree servers. At launch, hyprpilot merges the catalogue and projects it onto the vendor's native MCP surface — you keep one catalogue, every vendor reads it.

The mcps catalogue

Each mcps entry carries either a file path or an inline mcp_servers map (exactly one — declaring both, or neither, is a load error). File paths follow the standard { "mcpServers": { … } } shape that Claude Code, Codex, and Cursor all read, so you can drop your existing ~/.claude.json straight in:

profiles:
  - id: engineer
    agent: claude-code
    mcps:
      - file: ~/.claude.json
      - file: ~/.config/hyprpilot/mcps/team.json
        ignore:
          - scratch-*
          - '*-internal'

Inside each file:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}" }
    }
  }
}

Files iterate in order; a later file's server overrides an earlier one of the same name. A single malformed file warns and is skipped rather than aborting the launch. Transport is inferred by field presence (command → stdio, url → http/sse). Everything except the typed hyprpilot policy block stays opaque, so vendor-specific server fields pass through untouched.

Fields

Field	Type	Default	What it does
file	path	—	An { "mcpServers": { … } } JSON file. Exactly one of file / mcp_servers.
mcp_servers	map	—	Inline server map, same shape as the file's mcpServers value.
include	string[] (globs)	unset	When set, only server names matching a pattern are kept.
ignore	string[] (globs)	[]	Server names matching any pattern are dropped. Beats include on overlap.

Inline servers

If you want a one-off server without a file, declare mcp_servers on the entry directly:

mcps:
  - mcp_servers:
      hyprpilot-nvim:
        command: uvx
        args:
          - hyprpilot-nvim-mcp

Filtering servers

include and ignore are optional glob arrays per entry. ignore drops server names matching any pattern before they reach the agent. include is an allow-list: when set, only matching names survive, so a server added to the file later stays out until the list names it. A name matching both is dropped, and an empty or absent include applies no allow-list. Globs anchor against the full server name — work-* matches work-foo but not pre-work-foo.

mcps:
  - file: ~/.config/hyprpilot/mcps/personal.json
    include:
      - gitlab

Per-profile override

mcps on a profile wholesale-replaces the shared catalogue for that profile. mcps: [] means "no MCPs at all" — handy for a sandboxed read-only profile. To share one catalogue across every profile, put it in a patches entry instead of repeating it.

Reserved names

Each in-tree server's resolved name is reserved — by default hyprpilot, hyprpilot-skills, and hyprpilot-harness (see the mcp block). A configured server of that name is replaced by the injected entry, and renaming a server via mcp.<server>.name moves which name is reserved.

Tool policy

Each server entry takes an optional hyprpilot block for tool visibility and approval policy:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "hyprpilot": {
        "includeTools": ["read_*", "list_*"],
        "excludeTools": ["delete_*"],
        "autoAcceptTools": ["read_*"],
        "autoRejectTools": ["delete_*"]
      }
    }
  }
}

Field	Type	Default	What it does
includeTools	string[] (globs)	unset	Visibility allow-list. Unset = no allow-list; [] = deny all.
excludeTools	string[] (globs)	[]	Visibility deny-list. Exclude beats include.
autoAcceptTools	string[] (globs)	inherited	Approval accept list. Falls back to mcp.autoAcceptTools.
autoRejectTools	string[] (globs)	inherited	Approval reject list. Reject beats accept.

• Globs are server-relative — write read_*, not mcp__filesystem__read_*; the mcp__<server>__ prefix is implicit.
• includeTools / excludeTools control visibility; autoAcceptTools / autoRejectTools control approval.
• Servers with no per-server override inherit the mcp block's autoAcceptTools (default ['*']) / autoRejectTools.
• Every other key on a server definition passes through to the vendor untouched.

The mcp block

hyprpilot ships four in-tree MCP servers. Each is its own subcommand, its own process, and its own catalogue entry, so each can be enabled, renamed, and given a tool policy independently:

Server	Subcommand	Default name	Serves	Default
General tools	hyprpilot mcp serve	hyprpilot	open	enabled
Skills	hyprpilot mcp skills	hyprpilot-skills	skills (tools, resources, SEP-2640 skills/*) and prompts	enabled
Agent harness	hyprpilot mcp harness	hyprpilot-harness	list_profiles / spawn / session_*	disabled
Passthrough	hyprpilot mcp passthrough	hyprpilot-passthrough	the tools mcp.passthrough.tools declares	disabled

The mcp block gates and configures all four:

mcp:
  enabled: true # master gate over every in-tree server
  autoAcceptTools:
    - '*'
  autoRejectTools: []

  serve:
    enabled: true

  skills:
    dirs:
      - dir: ~/.config/hyprpilot/skills
      - dir: ~/.team/shared-skills
        ignore:
          - work-*
          - '*-experimental'
      - dir: /mnt/nfs/team-skills
        watch: false
    prompts:
      - dir: ~/.config/hyprpilot/prompts
    system_prompts: true

  harness:
    enabled: true
    max_sessions: 64
    max_live_sessions: 0

Field	Type	Default	What it does
enabled	bool	true	Master gate. false auto-injects nothing, whatever the per-server blocks say.
serve	object	—	The general-tools server. See below.
skills	object	—	The skills server. See below.
harness	object	—	The agent-harness server. See below.
passthrough	object	—	The HTTP passthrough server. See below.
autoAcceptTools	string[] (globs)	['*']	Default tool-approval accept list, copied onto servers with no per-server policy.
autoRejectTools	string[] (globs)	[]	Default tool-approval reject list. Reject beats accept.

A profile's mcp field wholesale-replaces this block. autoAcceptTools / autoRejectTools are glob-validated at config load (like the ignore lists) — a malformed glob errors at startup with a field-path message instead of silently failing at match time.

Every per-server block accepts enabled, name, autoAcceptTools, and autoRejectTools. The default names in the table above are not compiled in — they are seeded as mcp.serve.name / mcp.skills.name / mcp.harness.name / mcp.passthrough.name in the shipped [[patches]], and the injector reads that field and nothing else, so a rename is a config edit. name is what the vendor prefixes tool calls with, so renaming the skills server to docs turns mcp__hyprpilot-skills__read_skill into mcp__docs__read_skill — anything that addresses a tool by name (a skill file, a system prompt) has to follow. The skill:// and hyprpilot:// resource URIs are fixed schemes and never change. A per-server autoAcceptTools overrides the block-level default rather than merging with it.

mcp.serve

The general-tools server — the surface for things that are neither a skills read nor an agent launch. open today. Stateless, so nothing to reload or reap.

mcp.skills

Field	Type	Default	What it does
dirs	{ dir, include?, ignore?, watch? }[]	XDG root	Skill roots — trees of SKILL.md bundles, at any depth. Watched by default.
prompts	{ dir, include?, ignore?, watch? }[]	[]	Prompt directories — every *.md directly inside is served as an MCP prompt. Globs match the prompt name.
system_prompts	bool	true	Also serve the launched profile's own system_prompt files as prompts, so an edited one can be re-invoked live.

This server is also gated on having something to serve: with no skill and no loadable prompt, nothing is injected — and a profile with a system_prompt gets it even with no skills, because that prompt is served. See Skills & the hyprpilot MCP Server for what it exposes.

system_prompts is seeded snake_case; override it in the same spelling (see the warning under mcp.harness). The root defaults to ~/.config/hyprpilot/skills, seeded through an unscoped patches entry rather than a compiled default, so a user layer's patches extends the seed instead of replacing it.

dirs entries

Field	Type	Default	What it does
dir	path	—	Skill root to scan. Missing roots warn and are skipped.
include	string[] (globs)	unset	When set, only skill paths matching a pattern load from this root (* crosses /). An empty or absent list applies no allow-list.
ignore	string[] (globs)	[]	Skill paths matching any pattern are skipped. Beats include on overlap. First root wins on path collision.
watch	bool	true	Watch this root and announce changes. Seeded on for the default root. Turn it off for a root on a filesystem that cannot deliver events (NFS, SSHFS, most FUSE) — those accept the watch and never fire, so edits there need reload.

mcp.harness

Field	Type	Default	What it does
max_depth	int	1	Levels of delegation allowed. See below.
max_sessions	int	64	Finished sessions retained before the oldest are evicted. 0 retains every one. See below.
max_live_sessions	int	0	Sessions allowed to run at once before spawn is refused. 0 allows any number. See below.
notify_on_complete	bool	true	Push a completion event into the lead's context when a turn finishes. See Agent Harness.
includeProfiles	string[] (globs)	unset	Profile ids this launch may delegate to. Unset applies no filter; [] means none. See below.
excludeProfiles	string[] (globs)	[]	Profile ids this launch may not delegate to. Beats includeProfiles on overlap.
mcp	mcp block	unset	The [mcp] block every delegate this harness spawns receives. See below.

max_depth, max_sessions, max_live_sessions and notify_on_complete are seeded by the compiled defaults, so your own config overrides them per field without restating the rest.

Write a seeded key the way the seed writes it

Config keys accept both snake_case and camelCase, but patches merge by key string before anything is typed. These four are seeded snake_case, so overriding one as maxDepth / maxSessions / maxLiveSessions / notifyOnComplete arrives as a second key and fails config load with duplicate field. The same holds for the other seeded multi-word keys, mcp.skills.system_prompts and mcp.passthrough.timeout_seconds. Every unseeded key is unaffected — there is nothing to collide with.

includeProfiles / excludeProfiles are the launcher's scope, distinct from the target's own profiles.harness opt-in. The two AND — a glob here narrows what is already nominated and can never promote a profile that never opted in. * crosses / (same globset semantics as $match.profile), so personal/* reaches personal/kilic/glm-5.2. Full treatment in Agent Harness → Scoping delegation per launch.

mcp.harness.max_depth

How many levels deep delegation may go. It is read in exactly one place — the mcp.harness block a gate is deciding on — and answers two questions with the same comparison, depth < max_depth:

• whether a session running at that depth gets a harness server injected at all, and
• whether a running sidecar at that depth may spawn.

Value	Effect
1	Default. You delegate; your delegates do not. They get no harness server at all.
2	Your delegates get a harness and may delegate once more. Theirs may not.
0	Nothing anywhere gets a harness injected, and nothing may spawn.

The injection half is absolute — no enabled: true re-opens it, because a harness at the cap could only ever refuse spawn, so injecting one buys a long-lived process and seven tools that exist to error.

Raising it is a resource decision, not a security one. A max_live_sessions ceiling, where you set one at all, covers only its own sidecar's table, so an extra level lets N delegates each run N sessions — a fan-out no single ceiling catches and the lead that started the tree cannot see. There is deliberately no upper bound; the trade is yours to make.

mcp.harness.max_live_sessions

How many sessions this sidecar may have running at once. Past it, spawn is refused with a message naming the knob; session_kill on a finished or runaway session frees a slot. It bounds breadth where max_depth bounds recursion.

It is 0 — off — by default. How many agents are worth running at once is a property of your machine and your work, and hyprpilot has no way to guess it, so it refuses nothing until you say otherwise. Set a number on a shared or resource-tight host, where a profile's command being an arbitrary binary makes an unbounded fan-out something the host pays for. Leave it at 0 where an agent fanning out wide is exactly the point.

mcp.harness.max_sessions

How many finished sessions are retained before the oldest are evicted with their transcripts. 0 retains all of them.

Running sessions are outside this count, not merely spared by it — they hold a live model connection rather than history. Counting one would spend the retention budget on work still in flight, so with the concurrency ceiling off, enough concurrent agents would evict every transcript the cap exists to keep. session_list follows the same priority: running sessions lead, then most recent turn first.

Only distinct spawns grow the table — a conversation reuses its session however many turns it runs — so this bounds a long-lived sidecar's memory and temp directories without a tool you have to remember to call.

mcp.harness.mcp

An mcp block, same shape as the top-level one, applied to every delegate this harness spawns. It is folded per key onto whatever the delegate profile itself resolved: a key you set here wins, a key you leave unset inherits.

mcp:
  harness:
    enabled: true
    # what the agents I delegate to get
    mcp:
      serve:
        enabled: false
      skills:
        dirs:
          - dir: ~/.config/hyprpilot/skills/delegate

Distinct from includeProfiles, which answers which profiles you may reach. This answers what those agents can reach once running.

Setting harness.enabled: true here does not give a delegate a harness — the depth gate is checked first and does not consult enabled. Setting harness.max_depth here does, because the gate reads max_depth from the block it is deciding on, and the overlay is folded into that block. That is the supported way to hand one specific delegation an extra level without raising the cap for everything.

Because the fold is per key and not wholesale, a block naming only skills.enabled keeps the delegate's skills.dirs. Arrays replace rather than merge, so autoAcceptTools set here is the delegate's whole accept list.

Off by default, and that is a security property rather than a preference. A profile's command is an arbitrary binary, so anything that can call spawn executes commands as you. Turn it on deliberately — see Runtime → Agent Harness.

mcp.passthrough

Field	Type	Default	What it does
enabled	bool	false	Inject the server. Also needs at least one tool.
tools	{ name, description?, input_schema, url, body? }[]	unset	The tools served. Keyed by name, so a later layer retargets a tool.
timeout_seconds	int	300	Per-request timeout, connect through the last byte. Seeded, so write it snake_case.

Tool field	Type	What it does
name	string	MCP tool name, 1-128 characters of [A-Za-z0-9_.-]. Unique within the block.
description	string	Listed as written. This is how the agent learns what the tool is for.
input_schema	JSON object	Listed as the tool's inputSchema. Advertised, not enforced.
url	http(s)://	Every call POSTs here. Validated at config load.
body	JSON object	Static fields sent with every call; the call's arguments are laid over it and win on collision.

[mcp.passthrough]
enabled = true

[[mcp.passthrough.tools]]
name = "decide"
description = "Ask the decision model a yes/no question."
url = "https://decide.internal.example/v1/decide"
body = { model = "decision-small", stream = false }
input_schema = { type = "object", properties = { question = { type = "string" } }, required = ["question"] }

Off by default, and like skills it is also gated on content: enabled with no tools injects nothing. The call contract and the argv caveat are in Runtime → HTTP Passthrough.

Vendor projection

The merged catalogue and policy are projected into each vendor's native shape at launch:

Vendor	Servers via	Policy via
claude-code	--mcp-config <path> (0600 temp file)	--allowedTools / --disallowedTools (mcp__server__tool)
codex	-c mcp_servers.<name>.* overrides	exact-name enabled_tools / disabled_tools / approval_mode
opencode	OPENCODE_CONFIG_CONTENT mcp.servers	ordered permissions rules in the same config (server_tool)
amp	--mcp-config <path> (0600 temp file)	not projected — set amp.tools.disable in the settings file

Codex does not support wildcard tool patterns in those fields, so wildcard patterns are skipped for Codex with a warning. Provider-native arguments you pass after -- (or env you set on the agent) suppress the generated equivalents.

Secrets in the vendor handoff

MCP server entries commonly carry secrets — bearer tokens in HTTP headers, API keys in stdio env. hyprpilot keeps expanded secret material out of the vendor's argv, because a process's argv is world-readable through /proc/<pid>/cmdline on Linux:

• claude-code — the resolved MCP config (with ${VAR} header/env references already expanded) is written to a per-launch 0600 temp file and passed as --mcp-config <path>. The file is created owner-only from the start, so the secret never lands in argv. A launch that waits on the vendor — a headless --prompt / --file run, or a turn the agent harness drives — deletes the file as soon as the vendor exits. An interactive launch exec()s into the vendor, which leaves nothing behind to delete it, so each launch sweeps hyprpilot-mcp-*.json files older than 24 hours from the temp dir before writing its own.
• codex — bearer tokens are projected as mcp_servers.<name>.bearer_token_env_var / env_http_headers references (the env var name, not its value), so codex resolves the secret from its own environment.
• amp — the same 0600 temp file as claude-code, holding a bare { "<name>": { … } } server map. An amp --no-tui runner launched this way reads the file when it starts, and Amp restarts runners into CLI updates with the same flags, so a runner that outlives the 24-hour sweep restarts without the file — relaunch it through hyprpilot, or set amp.runner.autoUpdate.enabled to false.
• opencode — the generated config rides the OPENCODE_CONFIG_CONTENT env var. Env is not world-readable like argv, but does inherit into child processes; this is the residual, lower-risk surface.