MCP server - Guild

The Guild CLI includes an MCP (Model Context Protocol) server that exposes Guild operations as tools for MCP clients. Client agents call these tools to read and act on Guild resources. This page describes what each category of tool returns, so you can parse the results reliably.

Output format

Every tool returns its result in the content[0].text payload. The format depends on what the tool does:

Data-returning tools return a structured JSON string. The tool serializes the response data with JSON.stringify(data, null, 2), so the text is valid, indented JSON that a client agent can parse directly.
Action-taking tools return narrative plain text that describes the result of the action.
Errors return a plain text error string and set isError: true.

Data-returning tools return JSON, not human-readable narrative text. Parse content[0].text as JSON instead of scraping formatted output.

Data-returning tools

These tools return structured JSON. They cover the current user, list endpoints, and single-object get endpoints.

Tool	Returns
`guild_whoami`	The current user as JSON.
`guild_list_workspaces`	A JSON list of workspaces.
`guild_list_contexts`	A JSON list of contexts.
`guild_search_agents`	A JSON list of matching agents.
`guild_list_agent_versions`	A JSON list of agent versions.
`guild_list_sessions`	A JSON list of sessions.
`guild_list_triggers`	A JSON list of triggers.
`guild_get_trigger_sessions`	A JSON list of sessions spawned by a trigger.
`guild_list_credentials`	A JSON list of credentials.
`guild_list_integrations`	A JSON list of integrations.
`guild_get_integration_operations`	A JSON list of integration operations.
`guild_get_workspace`	A single workspace as JSON.
`guild_get_context`	A single context as JSON.
`guild_get_agent`	A single agent as JSON.
`guild_get_integration`	A single integration as JSON.
`guild_get_session`	A JSON object of the shape `{session, events}`, where `events` is bounded to 20 events.
`guild_get_session_events`	A JSON object of the shape `{events}`.

Pagination

Some data-returning tools can return more rows than fit in a single response. Use cursor pagination to walk the full result set instead of only the most-recent page. These tools support pagination:

guild_list_sessions
guild_list_triggers
guild_get_trigger_sessions
guild_get_session_events

Each of these tools accepts an optional cursor parameter. When more rows remain, the response includes a nextCursor string. Pass that value verbatim as the cursor argument on your next call to fetch the next page. When the response omits nextCursor, you have reached the end of the result set. For guild_get_session_events, the response payload places the rows in an events array ordered ascending by ID. Walk the full event history by following nextCursor until it is absent.

Action-taking tools

These tools perform an action and return narrative plain text describing the result.

guild_chat
guild_send_message
guild_interrupt_session
guild_add_workspace_agent
guild_remove_workspace_agent
guild_publish_context
guild_get_agent_readme

Prefer the terminal? Use guild api, the authenticated CLI escape hatch that calls the Guild REST API directly and prints the raw JSON response.

​Output format

​Data-returning tools

​Pagination

​Action-taking tools

​Related

Output format

Data-returning tools

Pagination

Action-taking tools

Related