The built-in MCP server

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. Most of the assistant-only surface (memory, channel, routines, delegation) is exposed in both modes, but high-impact mutations like file writes and shell are hidden from assistant-attached sessions by default. 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 inside the assistant’s working directory. Claude reads it at session start and launches the glueprint-mcp binary listed inside. For assistant-context spawns, the config is written to a per-session location instead of the shared working tree to keep the bootstrap token out of sibling sessions.
• 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

Glueprint assistants can spawn and manage their own sub-sessions. The session tools come in two halves:

Mutation (each routes through the permission UI):

• gp_start_session — spawn a new agent session under the assistant.
• gp_stop_session — gracefully end a session.
• gp_send_session_message — inject a chat message into a running session.
• gp_approve_permission / gp_deny_permission — act on a sub-session’s pending permission.
• gp_answer_question — answer a pending question in a sub-session.

Queries (auto-approved, read-only):

• gp_list_sessions, gp_get_session_status, gp_get_session_events, gp_get_pending_actions.

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.

These always require user approval. They’re visible in human-initiated sessions and hidden by default in assistant-attached sessions — see Assistant mode vs. session mode below.

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; what differs is the tool list it advertises:

• Human-initiated session — you start the session yourself from the Sessions view (or the portal / mobile). The full tool list is visible to the agent, including file I/O and shell. You’re driving and you’ll see the approval prompts for anything risky.
• Assistant-attached session — the assistant spawned the session. The tool list is filtered: file I/O (gp_read_file, gp_write_file, gp_edit_file), shell (gp_bash), and session-control mutations are hidden entirely. The agent doesn’t see them in its tool list at all. This is what makes assistant mode narrower by default — the assistant can’t even attempt the high-risk mutations unless someone explicitly grants access.

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

A misbehaving agent that tries to call a tool that’s been hidden gets back a “tool not found” error.

Approval policy

Each tool falls into one of three buckets:

Bucket	Behavior
Auto-approved	The call runs without prompting. Used for low-risk reads, channel messages, journals, append-mode memory, delegation status.
Always asks	The call pauses for a permission prompt. Used for memory replace mode, routine create/update/delete, session mutations, file writes, shell.
Hidden in assistant mode	The call isn’t advertised; the agent can’t try it. Used for file I/O, shell, session control in assistant mode.

The buckets are server-enforced. A misbehaving agent that tries to call a hidden tool gets back a “tool not found” error.

Configuration

The built-in server itself has no on/off toggle and no per-tool override surface in the UI. The buckets 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 auto-approve / always-ask split here — they can tighten (turn an auto-approved tool into ask-or-block) but not loosen below what the bucket above already requires.

Related topics

• 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.