The built-in MCP server — Glueprint Docs

Every Glueprint session, whether you started it yourself or an assistant spawned it, gets a built-in MCP server attached automatically. It’s what lets the underlying coding agent call into Glueprint — to read or write a file, run a shell command, write to memory, post to a channel, create a task, kick off a sub-session, and so on. You can’t remove it and you don’t need to register it as an extension.

The tool surface the agent actually sees depends on whether the session is assistant-attached or human-initiated. Memory, channel, routines, and delegation are exposed in both modes. High-impact mutations — file writes, shell, session creation, project management — are hidden from assistant-attached sessions, and an assistant is confined to the sessions in its own delegation tree even for the tools it can see. A human-initiated session has host-wide reach, matching what you can do yourself in the app. See Assistant mode vs. session mode below.

This page is the reference for what the server exposes and how it behaves.

How it runs

The MCP server is a separate binary (glueprint-mcp) that Glueprint spawns once per agent session. It talks to the agent over newline-delimited JSON-RPC 2.0 on stdio (each message is a JSON object followed by \n; there is no Content-Length framing). It talks back to the Glueprint engine over HTTP on 127.0.0.1 for things that need to reach the UI — approvals, questions, notifications.

Each session gets a single-use bootstrap token at spawn time. The MCP subprocess exchanges that token at startup for a longer-lived session-scoped capability. The bootstrap is invalidated after first use, so if a stray sibling process tries to claim the same session it fails closed.

The protocol version Glueprint negotiates is "2025-11-25". Permission responses use the standard MCP { "behavior": "allow", "updatedInput": { ... } } envelope.

How it gets attached to each harness

The built-in server is always present. How it’s plumbed in differs per harness:

Claude Code — Glueprint writes an MCP config file and points Claude at it with --mcp-config. Claude reads it at session start and launches the glueprint-mcp binary listed inside. The file goes to a per-session path under Glueprint’s storage root (mcp-spawn/<session-id>.json), never into your working tree: that keeps the bootstrap token away from sibling sessions sharing the same directory, and keeps an untracked config file out of your repo. It is deleted once the token is exchanged.
Codex CLI and ACP agents (Gemini and others) — the same binary args are inlined directly into the agent’s mcpServers field on session start. No file is written; the spawn list rides in-protocol.

Any extension MCP servers you add (see Extensions) are merged into the same config / protocol field. The built-in glueprint entry is always first.

Scopes: where MCP servers can come from

This is the part that trips people up. There are several distinct scopes an MCP server can live at, and they layer differently. Knowing which scope you’re editing is important — they’re not interchangeable.

Scope	Who edits it	Where it’s stored	What it applies to
Built-in (`glueprint`)	Nobody — always on	Hardcoded into every spawn	Every Glueprint session (assistant or human-initiated).
Assistant-scoped	You, in the assistant’s Extensions tab	Glueprint’s assistant config	Only sessions spawned by that specific assistant. Bound to assistant identity.
Project-scoped (Claude Code)	You, by hand in `~/.claude.json` under `projects.<path>.mcpServers`. Glueprint has no UI for this.	The Claude Code config file in your home directory	Every session Claude Code runs in that working directory — assistant-attached OR human-initiated. Bound to filesystem path.
User-scoped (Claude Code)	You, by hand in `~/.claude.json` at the top-level `mcpServers`	The Claude Code config file in your home directory	Every Claude Code session on the machine. Bound to your account on this device.

A few rules that fall out of this:

Glueprint only manages the assistant scope. The Extensions tab is the only Glueprint UI for adding MCP servers. Anything else lives in Claude Code’s own config.
Project scope is not the same as the Glueprint Project concept. A Glueprint Project (the thing you set up under Settings > Projects) is just a folder Glueprint has registered for sessions. Claude Code’s “project scope” is filesystem-scoped MCP config that applies whenever Claude runs in that folder, regardless of whether Glueprint knows about the folder.
Inherited subsection in the Extensions tab shows only the user-scope MCPs from ~/.claude.json — never the project-scope entries, even though both live in the same file. This is deliberate; project-scope entries are visible to Claude Code directly and don’t need to be re-shown in Glueprint.
All scopes stack additively. A given session sees the built-in server + whatever assistant-scoped servers apply + whatever Claude-Code-managed servers (user-scope and project-scope) apply. If two servers share a name, Claude Code’s own merge logic decides which wins; Glueprint doesn’t interpose.

Practical guidance: if you want an MCP server “for this assistant,” use the Extensions tab. If you want one “for everything I do in this repo,” add a project-scope entry in ~/.claude.json. If you want one “everywhere,” add a user-scope entry. They’re not substitutes for each other.

Tools the server exposes

The tools are grouped by what they do. Tool names match exactly what the agent sees.

Core protocol (always auto-approved)

permission_prompt — routes a permission request through the desktop UI.
user_question — routes a single or batched question through the desktop question UI.

Channel (the assistant’s voice)

gp_send_channel_message — post a message to the assistant’s chat channel. Auto-approved. This is how the assistant talks to you; it’s also the rule the overlay enforces (“all user-visible output goes through this tool”).
gp_read_channel_messages — read recent messages from a personal assistant’s channel.
gp_search_channel_history — search the channel for keywords.

Memory

gp_remember — write durable knowledge to long-term memory. Required: assistant_id, type (one of user, project, teams, organization, feedback, reference), title, content. Optional: mode (append — the default and auto-approved — or replace, which requires user approval).
gp_journal — append a timestamped entry to today’s journal. The file path is computed per-day and created automatically. Auto-approved.
gp_recall — substring search across the long-term files, reference files, and journals for an assistant.
gp_forget — delete a specific long-term file. Requires user approval every call.

What the writes touch on disk:

Append entries land in memory/long-term/{type}_{slug}.md and update the assistant’s MEMORY.md index.
Journal entries land in memory/journal/YYYY-MM-DD.md, with a # YYYY-MM-DD heading on first write of the day and an ## HH:MM UTC heading per entry.
All writes are atomic (temp-file + rename) so a crash mid-write can’t corrupt the file.

Boards and tasks

gp_list_boards, gp_list_board_members, gp_list_tasks, gp_search_tasks, gp_get_task — read-only board/task queries.
gp_create_task, gp_update_task, gp_move_task_status, gp_assign_task, gp_archive_task — task mutations.
gp_append_work_log — append a work-log entry to a task.

Visibility is server-gated: the assistant only sees boards and tasks the account permits. A task move that’s not allowed by the board’s task flow definition is refused at the server.

Routines

gp_list_routines — list the assistant’s scheduled instructions.
gp_create_routine, gp_update_routine, gp_delete_routine — create / modify / delete a routine. Each call routes through the permission UI so you see the cron expression and body before the file lands. There is no auto-approved path.

A routine ends up at instructions/<slugified-name>.md inside the assistant’s directory.

Sessions

Both kinds of session can inspect and drive other sessions on the host. What differs is reach: an assistant is confined to its own delegation tree (the sessions it spawned, and their descendants), while a human-initiated session can act on any session on the host.

Queries (auto-approved, read-only):

gp_list_sessions, gp_get_session_status, gp_get_session_events, gp_get_pending_actions.

Creating a session — the two tools are mutually exclusive by caller:

gp_start_session — assistants only. Spawns a child down the delegation ladder (main_assistant -> assistant_task -> project_work). A human-initiated session that calls it is told to use gp_create_session.
gp_create_session — human-initiated sessions only. Creates an ordinary interactive session in a project, optionally in a fresh worktree, optionally with a starting prompt, model, permission mode, and reasoning effort. Assistants are refused; they create children through delegation.

Driving a running session (available in both modes; each call asks for approval):

gp_interrupt_session — cancel the current turn; the agent process stays alive.
gp_steer_session — inject text into a turn already in flight. If the session is not mid-turn you get a conflict telling you to queue with gp_send_session_message instead.
gp_send_session_message — queue a chat message for the session.
gp_rename_session.
gp_approve_permission / gp_deny_permission — act on another session’s pending permission.
gp_answer_question — answer another session’s pending question.
gp_stop_session — gracefully end a session.

Lifecycle and per-session settings (human-initiated sessions only; assistants are refused):

gp_archive_session — stops a live process first, then archives. Refused while the session is mid-spawn.
gp_unarchive_session — refused if the session’s working directory no longer exists.
gp_set_session_model, gp_set_session_permission_mode, gp_set_session_collaboration_mode, gp_set_session_reasoning_effort.

Git worktrees

gp_list_worktrees — read-only.
gp_create_worktree — create one, either auto-named or on a branch you name. The destination directory is always derived by Glueprint from the repository and branch; the agent never supplies a path.
gp_remove_worktree — remove one.

Sessions rooted in the worktree are stopped and archived automatically as part of removal; reopen one with gp_unarchive_session. An in-flight worktree creation still returns 409 until it settles, and force does not override that. Terminals and language servers running there are not stopped for you, so close those yourself if the removal reports the directory is busy.

Worktrees belong to a project rather than to a session, so assistants may use these tools outside their delegation tree. The server checks the capability token and that the target worktree really belongs to the named project.

Projects

gp_create_project, gp_update_project, gp_delete_project — human-initiated sessions only; assistants are refused. Deleting is refused while work items still reference the project.

(gp_list_projects is read-only and available in both modes — see Discovery and identity.)

Terminals

gp_list_terminals — read-only.
gp_read_terminal — returns the terminal’s current screen with ANSI escape sequences stripped. Read-only, no prompt.
gp_create_terminal — always asks. The working directory is sandboxed to the project’s repository and its worktrees.
gp_terminal_send_text — type into a terminal. submit defaults to true, which appends Enter and therefore runs what was typed; the approval card distinguishes the two.
gp_close_terminal.

The write tools use a grant model instead of prompting per keystroke, which would be unusable. Approving gp_create_terminal grants that terminal to the session. Sending to or closing a terminal the session did not create asks once, and approval grants it from then on. Grants are scoped per session and per (project, terminal) pair, and they vanish when the session ends — nothing persists to disk. Terminals opened this way appear in the desktop terminal list and for portal and mobile viewers, the same as ones you open yourself.

Two things worth knowing: terminal reads are host-wide and never prompt, so an agent can screen-read any terminal on the machine, including one holding credentials or a live SSH session. And reading a terminal flushes its pending output to other viewers first, so an agent’s read never costs you output.

Mobile emulator

gp_emulator_list, gp_emulator_screenshot, gp_emulator_ax, gp_emulator_logcat — read the device: what is available, what is on screen, the view hierarchy, and the log.
gp_emulator_tap, gp_emulator_swipe, gp_emulator_type, gp_emulator_button, gp_emulator_rotate, gp_emulator_launch — drive the device. Auto-approved: the effect is confined to the virtual device.
gp_emulator_boot, gp_emulator_shutdown, gp_emulator_install — each call routes through the permission UI. See The Mobile Emulator tab.

Files and shell

When the agent needs to read or modify files outside what its own tools cover, or run a shell command, the MCP server exposes:

gp_read_file, gp_write_file, gp_edit_file — file I/O.
gp_bash — run a shell command in the project directory.

All four ask for approval on every call, in both modes. gp_read_file is visible to assistants; the three that modify state (gp_write_file, gp_edit_file, gp_bash) are not — see Assistant mode vs. session mode below. Paths are confined to the session’s project directory.

Schedules

gp_create_schedule, gp_update_schedule, gp_delete_schedule, gp_list_schedules — create and manage scheduled agent runs at the account level (separate from per-assistant routines).

Discovery and identity

gp_whoami — return identity context (the calling assistant id, the host user, who triggered this wake).
gp_list_agents — enumerate the AI agents installed on this host.
gp_list_projects — enumerate the projects Glueprint knows about.

Delegation

gp_set_delegation_status — a child session reports up to its parent (running / awaiting_parent / completed / failed). Auto-approved.

Notifications and tuning

gp_send_notification — send a desktop notification.
gp_set_heartbeat_interval — change how often this assistant gets a heartbeat wake.

Assistant mode vs. session mode

The same MCP binary runs in both contexts. Two things differ: which tools it advertises, and who the server will let act.

Human-initiated session — you started it yourself from the Sessions view (or the portal / mobile). Every tool is advertised, including file writes, shell, session creation, the per-session setters, and project management. Reach is host-wide, matching what you can do in the app. You see approval prompts for anything that mutates.
Assistant-attached session — an assistant spawned it. Not advertised: file writes (gp_write_file, gp_edit_file), shell (gp_bash), gp_forget, gp_create_session, archive/unarchive, the four per-session setters, project mutations, schedules, notifications, and heartbeat tuning. Of the tools that are advertised, session control is confined to the assistant’s own delegation tree.

Channel tools, memory tools, task tools, routine tools, worktree and terminal tools, and the read-only queries stay visible in both modes.

Filtering is a convenience, not the security boundary. The server does not refuse a call simply because the tool was left out of tools/list — enforcement lives one layer down, in the tool handler and in the engine. An assistant that names a regular-session-only tool anyway gets an explicit refusal (“assistants cannot use gp_archive_session; it is regular-session-only”) rather than a “tool not found”, nothing is mutated, and no approval card is shown to you for an operation that was never going to run. The engine applies the same rule to reach: a call that targets a session outside the caller’s delegation tree is refused there even if the tool itself was visible.

Approval policy

Each tool falls into one of four postures:

Posture	Behavior	Examples
Auto-approved	Runs without prompting.	Read-only queries; `gp_send_channel_message`; `gp_journal`; `gp_remember` in append mode; task and board mutations (already gated by the server); `gp_set_delegation_status`.
Always asks	Prompts on every call, in both modes.	`gp_create_session` and the session drivers and setters; worktree create and remove; project mutations; `gp_create_terminal`; routine create / update / delete; `gp_remember` in replace mode; file I/O and shell.
Asks regular callers only	Prompts a human-initiated session. An assistant’s call is unchanged from before — it goes through the Claude gate.	`gp_stop_session`, `gp_send_session_message`, `gp_approve_permission`, `gp_deny_permission`, `gp_answer_question`, `gp_forget`.
Asks once per resource	Prompts the first time, then runs freely for that resource.	`gp_terminal_send_text` and `gp_close_terminal` — once per terminal.

One exception to “always asks”: gp_write_file, gp_edit_file, and gp_bash are subject to the agent’s write, edit, and bash permission buckets. An agent configured always_allow for one of those runs it without a prompt, and one configured always_deny has it blocked without a prompt — the engine answers before the UI is involved either way. The buckets default to ask, so this only applies if you have configured them. Nothing else in the always-asks row has a bucket, so those genuinely ask every time.

The prompt is issued by the tool handler itself, which means it fires on every harness — Claude Code, Codex, ACP agents — rather than depending on Claude’s --permission-prompt-tool gate. That gate is still wired up for Claude, and tools that prompt in-handler are marked gate-skipped so a single call never produces two approval cards.

A tool’s own description states its approval behavior wherever that behavior is the same for both kinds of caller.

Configuration

The built-in server itself has no on/off toggle and no per-tool override surface in the UI. The postures above are baked in. What you can do:

Add assistant-scoped MCP servers alongside it — the Add MCP server button in the Extensions tab. Those servers see no filtering from Glueprint and run with whatever scopes their author defined. See Scopes above for what “assistant-scoped” means relative to project- and user-scoped servers.
Configure permission rules at the agent or assistant level under governance. Those rules apply on top of the postures above — they can tighten (turn an auto-approved tool into ask-or-block) but not loosen below what the posture already requires.
gp_write_file, gp_edit_file, and gp_bash honor the agent’s own write, edit, and bash permission buckets, so an always_deny there blocks them without a prompt. gp_read_file deliberately does not follow the read bucket: that bucket defaults to allow-everything, and quietly making MCP file reads promptless is a decision we have not taken. It asks every time regardless of the bucket. The session, worktree, project, and terminal tools have no buckets yet, so their prompts recur on every call.

Extensions — add your own MCP servers alongside the built-in one.
Memory — what the memory tools write and how it’s structured on disk.
Permissions and approvals — the runtime side of the auto-approve / always-ask split.
How Glueprint composes prompts — why the overlay tells the assistant to use these tools.