Skip to main content

MCP Server

The Zihin platform provides an MCP (Model Context Protocol) Server that lets you manage agents, schemas, triggers, secrets, and more directly from AI-powered IDEs and tools.

Overview​

FeatureDetails
Package@zihin/mcp-server
Tools113 (5 consumer + 3 consumer-profile + 10 consumer-ops + 51 builder-read + 44 builder-write) — the ceiling; each role and each way of signing in sees a subset, see RBAC
Resources21 (agents, schema-templates, models + 11 formal contracts zihin://schemas/{type} + 7 skills zihin://skills/{slug})
Skills7 expert playbooks (create agent, tools, triggers, diagnostics, governance, processes) — served by the server, installable natively per IDE
Guided Prompts3 with an API Key (setup-agent, add-tool, configure-webhook); 2 when signed in with your Zihin account (no configure-webhook) — see Guided Prompts
Tool AnnotationsAll 113 tools ship MCP ToolAnnotations (read-only/destructive/idempotent/open-world hints + title)
Output contractEvery result is JSON in content[0].text and in structuredContent; tool errors carry error.code (except arguments rejected by schema validation — see Error Handling); 10 tools declare an outputSchema — see Error Handling
Catalog cachetools/list, prompts/list and resources/list announce ttlMs of 5 minutes (resources/read: 60 s) — clients may cache the catalog
Server version2.5.0 (serverInfo.version of the remote server; the npm proxy has its own version)
Transportsstdio (via npm package) + HTTP Streamable (direct)
AuthenticationAPI Key (/mcp and /mcp/t/{tenant_id}) or, for a person, signing in with the Zihin account (/mcp/t/{tenant_id} only) — see Authentication
Server instructions

On initialize, the server sends role-aware instructions describing the main workflows, critical rules (e.g. endpoint.name must equal tool_definition.name) and the recommended contract-first flow — your MCP client injects them into the model's context automatically.


Setup​

There are two ways to connect:

WayWho it is forEndpoint
Sign in with your Zihin accountA person using an assistant (Claude Code, Codex, Cursor). No API Key: the assistant opens the browser, you sign in and the connection acts with your role in the companyhttps://llm.zihin.ai/mcp/t/{tenant_id}
API KeyIntegrations, automations and the npm proxy (@zihin/mcp-server)https://llm.zihin.ai/mcp (or /mcp/t/{tenant_id} with a key of the same company)

Sign in with your Zihin account​

Each company has its own MCP server URL:

https://llm.zihin.ai/mcp/t/{tenant_id}

{tenant_id} is the company UUID in lowercase, with no trailing slash — the URL is matched exactly, and any other spelling answers 404. You do not need to build it by hand: the console shows it, ready to copy, in Connect an assistant (MCP) — on the API Keys page and on the personal page My assistants (/assistentes), which every role can open, including member.

The first time the assistant calls the server, it gets a 401 with the discovery pointer, opens your browser, you sign in with your Zihin account and confirm the company. From then on the assistant renews the access on its own. A connection belongs to one company: to work with another company, add another connector with that company's URL.

Claude Code​

In the console, open Connect an assistant (MCP) and click Generate command. The command carries a --client-id that is yours alone in that company — it is what lets you revoke only that connection later:

claude mcp add --transport http --client-id YOUR_CLIENT_ID zihin-your-company https://llm.zihin.ai/mcp/t/{tenant_id}

Run it, then call any Zihin tool (or /mcp in Claude Code) to sign in. Generate the command again after revoking: the old client is deleted and a new one is created.

Codex​

codex mcp add zihin-your-company --url https://llm.zihin.ai/mcp/t/{tenant_id}

Codex registers its own client for the connector on the first sign-in.

Cursor​

Add a remote MCP server with the company URL (https://llm.zihin.ai/mcp/t/{tenant_id}), for example in .cursor/mcp.json:

{
"mcpServers": {
"zihin-your-company": {
"url": "https://llm.zihin.ai/mcp/t/{tenant_id}"
}
}
}

Cursor registers its own client and opens the sign-in when you enable the server.

Other assistants

Any MCP client that supports the MCP authorization flow (protected resource metadata, RFC 9728) can sign in the same way, but only Claude Code, Codex and Cursor have been verified. Claude Desktop and claude.ai are not covered yet — use an API Key there.

What the person can do through this connection — and what not — is in RBAC. How to see and revoke connections is in Connected assistants.

With an API Key​

The setups below use an API Key through the npm proxy. Install nothing — use npx to run the MCP proxy directly.

Claude Desktop​

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
"mcpServers": {
"zihin": {
"command": "npx",
"args": ["-y", "@zihin/mcp-server"],
"env": {
"ZIHIN_API_KEY": "YOUR_API_KEY"
}
}
}
}

Claude Code​

Add to your project's .mcp.json:

{
"mcpServers": {
"zihin": {
"command": "npx",
"args": ["-y", "@zihin/mcp-server"],
"env": {
"ZIHIN_API_KEY": "YOUR_API_KEY"
}
}
}
}

Or via CLI:

claude mcp add zihin -e ZIHIN_API_KEY=YOUR_API_KEY -- npx -y @zihin/mcp-server

Fastest path — plugin (MCP server + the 7 skills in one command; requires ZIHIN_API_KEY exported in your shell):

claude plugin marketplace add zihin-ai/zihin-mcp
claude plugin install zihin@zihin

Cursor​

Add to .cursor/mcp.json in your project root or ~/.cursor/mcp.json globally:

{
"mcpServers": {
"zihin": {
"command": "npx",
"args": ["-y", "@zihin/mcp-server"],
"env": {
"ZIHIN_API_KEY": "YOUR_API_KEY"
}
}
}
}

Windsurf​

Add to ~/.codeium/windsurf/mcp_config.json:

{
"mcpServers": {
"zihin": {
"command": "npx",
"args": ["-y", "@zihin/mcp-server"],
"env": {
"ZIHIN_API_KEY": "YOUR_API_KEY"
}
}
}
}

Codex (OpenAI)​

Add to ~/.codex/config.toml or .codex/config.toml in your project:

[mcp_servers.zihin]
command = "npx"
args = ["-y", "@zihin/mcp-server"]
env_vars = ["ZIHIN_API_KEY"]

The ZIHIN_API_KEY variable must be set in your shell. Alternatively, to set it inline:

[mcp_servers.zihin]
command = "npx"
args = ["-y", "@zihin/mcp-server"]

[mcp_servers.zihin.env]
ZIHIN_API_KEY = "YOUR_API_KEY"

VS Code (Copilot)​

Run the MCP: Add Server command, or add to .vscode/mcp.json:

{
"servers": {
"zihin": {
"command": "npx",
"args": ["-y", "@zihin/mcp-server"],
"env": { "ZIHIN_API_KEY": "YOUR_API_KEY" }
}
}
}

Gemini CLI​

gemini extensions install https://github.com/zihin-ai/gemini-cli-zihin

The extension asks for the API Key on install (stored in the system keychain) and sets up the MCP server plus a context file.

Other MCP Clients​

Any MCP client that supports stdio transport can use the @zihin/mcp-server package. The pattern is the same: run npx -y @zihin/mcp-server with the ZIHIN_API_KEY environment variable set.

Environment Variables​

VariableRequiredDescription
ZIHIN_API_KEYYesAPI Key for authentication
ZIHIN_MCP_URLNoOverride the server URL (default: https://llm.zihin.ai/mcp)

HTTP Transport​

For programmatic or server-to-server access (e.g., N8N, Make, custom scripts), the MCP Server is available directly via HTTP — no npm package needed.

EndpointMethodDescription
/mcpPOSTProcess a JSON-RPC request (API Key)
/mcp/t/{tenant_id}POSTSame server, scoped to one company: API Key of that company or a person's sign-in token

The server is stateless: every request is an independent POST, authenticated on its own (API Key or sign-in token). There is no session to open or close — no mcp-session-id header is issued, and GET /mcp and DELETE /mcp return 405. Responses are returned as text/event-stream (SSE) with a single message event.

Required Headers

All HTTP transport requests must include the Accept: application/json, text/event-stream header. Without it, the server returns 406 Not Acceptable.

Call a tool:

curl -X POST "https://llm.zihin.ai/mcp" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_agents",
"arguments": { "status": "published" }
}
}'

MCP clients that send initialize first still work: the server answers it, and each following request is handled on its own.

Catalog cache. Since server 2.5.0 the tools/list, prompts/list, resources/list and resources/templates/list responses carry the cache hints of the 2026-07-28 revision of the protocol: ttlMs: 300000 (5 minutes) with cacheScope: "private"; resources/read announces 60 seconds. A client that honours them does not need to refetch the catalog on every keepalive — the @zihin/mcp-server proxy already does this. The hints only appear to clients negotiating the 2026-07-28 revision; older clients see the same catalog without them.


Updating​

There are three separate things to update, depending on how you installed.

What you installedHow to updateHow to confirm
The npm proxy via npx -y @zihin/mcp-server (Claude Desktop, Cursor, VS Code, Windsurf, Codex, .mcp.json)Restart the MCP server or the client. If it still starts an old version, npx is reusing a cached copy: use "args": ["-y", "@zihin/mcp-server@latest"] so it checks the registry on every start.The proxy prints its version in the startup banner (client MCP logs) and reports it as serverInfo.version — from 2.2.2 on this is the real package version.
The Claude Code plugin (zihin@zihin)claude plugin update zihin@zihin, then restart Claude Code. Auto-update is off by default for third-party marketplaces.claude plugin list shows the installed version.
Skills copied by install-skillsRe-run the same install-skills command; it overwrites the copies.The command prints the source used (fonte: server or fonte: bundled).
The Gemini CLI extensiongemini extensions update zihin, then restart the session.gemini extensions list shows the installed version.

The tools, resources and prompts themselves come from the server, so they are always current regardless of the proxy version. Release notes: @zihin/mcp-server changelog.

Where the server is listed​

ChannelIdentifier
npm@zihin/mcp-server
Official MCP Registryai.zihin/mcp-server (npm package + remote endpoint https://llm.zihin.ai/mcp)
Claude Code plugin marketplacezihin-ai/zihin-mcp → zihin@zihin
Gemini CLI extensionzihin-ai/gemini-cli-zihin

Authentication​

The MCP Server accepts two credentials. Both resolve the company (tenant) and the role; every operation is scoped to that company.

CredentialAccepted onRole comes from
API Key/mcp and /mcp/t/{tenant_id} (key of that same company)The key's role
Sign-in token (a person signed in with the Zihin account, above)/mcp/t/{tenant_id} onlyThe person's role in the company — never the token

The generic /mcp endpoint keeps working exactly as before: API Key only. It does not announce a sign-in, so a client with a missing or revoked key gets a plain 401 instead of a login it could not use there.

API Key​

Same API Key system as the REST API. See Authentication for details.

HeaderFormatExample
X-Api-KeyDirectX-Api-Key: YOUR_API_KEY
AuthorizationBearer with zhn_ prefixAuthorization: Bearer YOUR_API_KEY
PrefixEnvironment
zhn_live_Production
zhn_test_Testing
zhn_dev_Development

The API Key determines the tenant context. On /mcp/t/{tenant_id}, a key of another company is refused with 403.

Signing in with the Zihin account​

The assistant sends Authorization: Bearer <token> with the token it got from the sign-in. You never handle this token: the assistant obtains and renews it. The server checks, on every request, that the token was issued for that exact company URL, that you are still an active member of the company, and that the connection was not revoked. Your role is read from the company at that moment — if an admin changes your role, the next request already uses the new one.

Discovery follows the MCP authorization spec: a 401 from /mcp/t/{tenant_id} carries a WWW-Authenticate header with resource_metadata, and the metadata lives at:

https://llm.zihin.ai/.well-known/oauth-protected-resource/mcp/t/{tenant_id}

Transport errors​

Authentication failures and the rate limit are answered by the HTTP transport, before the JSON-RPC layer (they are not tool results):

StatusWhenWhat the client should do
401Credential missing or invalid; sign-in token expired, issued for another URL, or from a revoked connection. On /mcp/t/{tenant_id} it carries WWW-Authenticate: Bearer error="invalid_token", …, resource_metadata="…"Sign in again (the assistant starts it) or fix the API Key
403Valid credential without access to this company: the person is no longer an active member (or was blocked), the token belongs to another company, the Claude Code client was generated for another person or company, or the API Key is from another company. No WWW-Authenticate challenge — signing in again does not helpUse the URL of a company you belong to
429 + Retry-AfterRate limit of the /mcp endpoint: 600 requests per minute per authenticated credential (each API Key, or each person × company when signed in); sessions sharing the same key add up in the same counter. The body is plain JSON {"error":"rate_limited","message":…}, not a JSON-RPC envelopeWait the number of seconds in Retry-After, then retry
503 + Retry-After: 15The sign-in check is temporarily unavailableRetry later; keep the token, do not sign in again
404Path is not a lowercase UUID, or ends with / (/mcp/t/{tenant_id}/)Use the exact URL shown in the console

Role-Based Access Control (RBAC)​

Each API Key has a role that controls which tools are available; a person signed in with the Zihin account has the role they hold in the company. See API Keys - Role System for how to create keys with specific roles.

113 is the ceiling, the full catalog. What each connection sees depends on the role, on the way it signed in and on whether the company has the process engine:

RoleAvailable ToolsDescription
owner113 (all)Tenant owner — full access
admin113 (all)Full access, except granting, ratifying and revoking integration grants (integrations:grant, owner only): consumer + consumer-profile + consumer-ops + builder-read + builder-write. Default for new keys.
editor59 (consumer + consumer-profile + builder-read)Read access (own sessions, aggregated profiles, builder reads). Write operations and consumer-ops are not even listed.
member5 (consumer only)End-user access: identify session, list agents, chat, view own sessions
RoleAPI KeySigned in with the Zihin accountCompany without the process engine (API Key / signed in)
owner, admin11389100 / 78
editor595952 / 52
member555

A company without the process engine sees only get_process_engine_status among the process tools. editor loses nothing by signing in: none of the tools left out below is available to that role anyway.

Tool categories:

CategoryCountOperationsRoles
consumer5Identify session, list published agents, chat, sessionsowner, admin, editor, member
consumer-profile3Aggregated cross-consumer reads (get_consumer_profile, list_consumers, list_consumer_sessions)owner, admin, editor
consumer-ops10Tenant-wide mutations on consumers/sessions (deny, suspend, engagement control, manual message, cancel turn, clear/archive/unarchive session) + process interventions (cancel instance, resolve incident)owner, admin only
builder-read51list_*, get_*, validate_*, compare_* + budget/approval reads + observability + execution search + process definitions/instances + integrations and grantsowner, admin, editor
builder-write44create_*, update_*, delete_*, toggle_*, publish_*, rollback_*, clone_*, test_*, set_agent_budget, process definition lifecycle, integrations (create, credential, grant, ratify, revoke)owner, admin only
Enforcement

RBAC is enforced centrally at registration and at call time: (1) tools/list only exposes tools allowed for the key's role — an editor never sees write tools; (2) every write tool carries a server-side role guard evaluated on each call (covers keys downgraded mid-session). Both derive from a single category registry, so new tools are protected automatically.

What a signed-in person cannot do​

A connection made by signing in acts on behalf of a person, from an assistant. It keeps the person's role but leaves out the tools that create a credential or a persistent way in — something that would keep working after the connection is revoked. These 24 tools are neither listed nor executable for a signed-in connection, whatever the role:

GroupTools
Credentialscreate_api_key, update_api_key, create_secret, update_secret
Persistent inbound access (webhook, schedule, external MCP)create_trigger, update_trigger, toggle_trigger, create_mcp_server, update_mcp_server
Indirect paths to the same effect (restoring recreates triggers and MCP servers; cloning copies triggers)rollback_version, rollback_snapshot, clone_agent
Automation that runs with the publisher's authoritypublish_process_definition, enable_process
Governancecreate_approval_policy, update_approval_policy, create_csp, update_csp, toggle_csp, delete_csp
Integrations shared with other companiescreate_integration, attach_integration_credential, grant_integration, ratify_integration_grant

Everything else the role allows stays available — creating and editing agents, schemas and personas, publishing agents, consumer operations, reads, and revoke_integration_grant for an owner (revoking only reduces access). To use one of the tools above, use the console or an API Key with the right role.

Anti-escalation

The create_api_key tool enforces anti-escalation: you cannot create an API Key with a role higher than your own. For example, an editor cannot create an admin key.

member keys see only their own conversations

A member key identifies one person. list_agent_sessions, get_session_history and resuming a session_id in chat_with_agent are limited to conversations owned by that person — the same rule as the REST API. A conversation that belongs to someone else, or that was opened on an external channel (WhatsApp, webhook, another API key) and therefore has no owner, is answered as NOT_FOUND rather than 403, so the key cannot probe for ids. Operator keys (admin, owner, editor) see the tenant's conversations.


Connected assistants​

Connections made by signing in are listed in the console, on My assistants (/assistentes) — available to every role, including member — and on the API Keys page.

  • Your connections: each assistant connected with your sign-in, per company, with the last use. Revoke cuts access immediately: the next request from that assistant is refused, and the client of that connection is invalidated so its renewals stop working too. To use the assistant again, it asks you to sign in again (in Claude Code, generate the command again).
  • The company's connections (admin and owner): the Company view lists everyone's connections and lets you revoke any of them.
  • Invalidation in progress / failed: revocation takes effect at once on Zihin's side; the final invalidation of the client finishes in the background. Until it does, the connection stays on the list with its state, and Try again is offered if it failed. While it is open, that client is refused.
  • Shared client: if the same client is used by other connections (for example, the same Codex connector linked to two companies), only this connection is cut and the console warns that a new authorization from that client may restore the old credential. Reconnect with a dedicated client — in Claude Code, Generate command creates one that is yours alone.

Leaving the company (or being removed) also ends access: the next request is refused with 403.


Tools Reference​

Consumer (5 tools)​

Available to all roles (owner, admin, editor, member).

ToolDescription
whoamiIdentify the current session: tenant name, role, and subscription plan
list_published_agentsList published agents available for chat
chat_with_agentSend a message and receive a response (includes tool_calls, model_used, execution_time_ms, message ids, blocks, truncation flags). Accepts client_message_id for idempotent resends and timeout_ms; integrations (admin/owner key) can also send consumer_key, consumer_display_name, consumer_channel, context, bindings, session_from and metadata — see below and Agent invocation contract
list_agent_sessionsList recent sessions for an agent, most recent first (filters: control_mode, consumer_key, roots_only to exclude sub-agent sessions). Returns the real total of the filter and has_more; offset must be a multiple of limit
get_session_historyMessage history of a session, read from the durable record and paginated with before/limit/next_before (user/assistant messages only; attachments as metadata) — see below

Example — chat_with_agent:

Tool: chat_with_agent
Arguments:
agent_id: "your-agent-uuid"
message: "List active contracts for this month"
session_id: "optional-session-id"

The response includes a session_id — pass it in subsequent calls to maintain conversation context.

chat_with_agent​

Since server 2.5.0 the tool has the same surface as POST /api/v2/agents/:id/stream.

Input fields (all optional besides agent_id and message):

FieldWho can send itBehavior
session_idany roleResume a conversation. A member key can only resume its own conversations (others are NOT_FOUND)
client_message_idany roleUUID generated by the client; makes the send idempotent for 24 hours (per agent and per person/key). Same id + same message → the stored answer is returned with idempotent_replay: true, without running the agent. Same id while the turn is still running → SESSION_BUSY. Same id with a different message → IDEMPOTENCY_CONFLICT. Use it in retries
timeout_msany roleOnly shortens the turn deadline of the channel. Values below 1000 are ignored and reported in ignored_fields. When it expires, the outcome is TIMEOUT as usual
attachmentsmember key onlyAttachments by reference: [{ path, filename?, content_type?, size_bytes? }] (max 10), where path is the object in the chat-attachments bucket ({tenant}/{user}/{file}) returned by the upload. url/base64 are not accepted. Authorization is the same as /stream: owner of the file + bound to the conversation. Other keys see the field in ignored_fields
consumer_keyadmin/owner keyIdentity of the end person the integration is speaking for (same as /stream). Resuming a session of another person returns CONFLICT
consumer_display_nameadmin/owner key, with consumer_keyDisplay name of that person. Applies from now on (profile and the current conversation); closed conversations keep the name of the time
consumer_channeladmin/owner key, with consumer_keyThe person's original channel (whatsapp, email, web, api…), not the transport. Lower-case free text; without it the channel is mcp
context, bindings, session_from, metadataadmin/owner keySee Agent invocation contract

Fields the key is not allowed to send are not an error: they come back in ignored_fields with a reason, and what was applied is listed in accepted_fields.

Output fields (additive to response, session_id, tool_calls, model_used, execution_time_ms):

FieldMeaning
user_message_id, assistant_message_idIds of the two messages written in the conversation record (the same ids the REST API returns)
blocksStructured blocks produced by the agent's tools (tables, files…). response is the readable text; do not re-print the blocks. content_from_blocks: true means the text was derived from the blocks
truncated, finish_reason, truncated_tool_callPresent only when the answer was cut by the output budget (truncated: true, finish_reason: "length"; truncated_tool_call when the cut landed inside a tool call)
client_message_id, idempotent_replayEcho of the id sent; idempotent_replay: true when the answer was replayed instead of running the agent
outcomeOutcome of the turn, same vocabulary as the done event of the SSE stream

get_session_history​

Reads the durable record of the conversation (not just the recent window the agent sees), oldest to newest within the page.

ArgumentMeaning
session_idId returned by chat_with_agent or list_agent_sessions
limitMessages per page (default 50, max 100) — the most recent ones before the cursor
beforePagination cursor: the next_before returned by the previous page (pass it unchanged)
Output fieldMeaning
messages[]Each message carries id, role, content, timestamp and, when present, blocks (with content_from_blocks: true if the text was derived from them) and attachments as metadata only — { filename, mime_type, size }, no URL
message_countTotal number of messages of the conversation — only when before is not sent. With before it is null
messages_before_cursorOnly with before: how many messages exist before the cursor
has_more, next_beforenext_before is the cursor for the next older page (null when there is nothing older)

list_agent_sessions complements it: its message_count and last_message_preview reflect the recent window of the conversation (up to 50 messages), while total is the real number of sessions matching the filter and has_more tells whether another page exists.


Consumer Profile (3 tools)​

Available to owner, admin, editor. Aggregated reads across consumers and sessions for the entire tenant.

ToolDescription
get_consumer_profileGet aggregated consumer profile (cross-session, cross-agent): display name, channels used, total sessions, total turns, agents interacted, product flags, timestamps
list_consumersPaginated list of consumers, ordered by last_seen_at (desc). Filters: search (substring in display_name or consumer_key), blocked (true = only denylisted, false = only not-denylisted)
list_consumer_sessionsPaginated list of a specific consumer's sessions (cross-agent, most recent first) — complements get_consumer_profile, which returns only aggregated counters

Consumer Ops (10 tools)​

Available to owner, admin only. Operational mutations that affect customer-facing behavior across the tenant.

ToolDescription
set_consumer_denylistAdd or remove a consumer from the tenant-wide denylist. When active, all messages from that consumer are bypassed cross-agent (no LLM, no quota)
set_session_controlChange a session's control_mode (engaged, suspended, manual_handoff). When ≠ engaged, the agent loop is bypassed for new messages on that session
set_engagement_controlEnd or restore the engagement between one agent and one consumer, without blocking the consumer tenant-wide. Evaluated after the tenant denylist and before session control
send_manual_messageSend a manual operator message through the same outbound channel as the agent (Twilio/Meta/webhook). Requires control_mode != engaged. Message is recorded as human-authored so the agent doesn't imitate the style if it resumes
cancel_agent_turnCancel an in-progress agent turn (mid-LLM, mid-tool, mid-stream). Useful for loop runaway, off-target responses, or compliance stops. In multi-agent (sub-agent) sessions, propagates via root_execution_id
clear_sessionClear the history of a conversation (irreversible — the conversation keeps existing, empty; the agent forgets what was said). Refuses with SESSION_BUSY while a turn is running and with SERVICE_UNAVAILABLE when the lock (Redis) is unavailable — on the local stdio transport there is no Redis, so use the HTTP server. Same rule as POST /api/v1/sessions/:id/clear
archive_sessionArchive a conversation (leaves the active list; reversible)
unarchive_sessionBring an archived conversation back to the active list. CONFLICT if it was not archived
cancel_process_instanceCancel a running process instance. Returns a command_id with status received — read the outcome with get_process_command
resolve_process_incidentResolve an incident of a process instance (same command_id pattern)
Session Lifecycle

These tools work together: set_session_control(manual_handoff) then send_manual_message(...) is the typical handoff pattern. cancel_agent_turn is for the in-flight turn; set_session_control(suspended) blocks the next one.


Agents (7 tools)​

ToolCategoryDescription
list_agentsreadList tenant agents (filters: status, type, include_archived)
get_agentreadAgent details with schemas
create_agentwriteCreate agent (model format: provider.model, e.g. openai.gpt-4.1-nano, or auto for intelligent routing)
update_agentwriteUpdate agent metadata. Also accepts chat_enabled (boolean) to enable/disable the agent on the native chat channel (chat.zihin.ai)
delete_agentwriteArchive or hard-delete agent
clone_agentwriteClone agent with schemas and optionally triggers
publish_agentwritePublish agent (validates all schemas first)

Schemas (5 tools)​

ToolCategoryDescription
list_schemasreadList schemas for an agent (filters: schema_type, include_inactive)
get_schemareadSchema details
create_schemawriteCreate schema with integrated validation
update_schemawriteUpdate schema with re-validation
delete_schemawriteRemove schema

Schema types: persona_config, api_config, workflow_config, skill_config, mcp_tool_config, mcp_resource_config

Contract-first workflow (avoids trial and error)

Each schema type has a formal contract exposed as a resource — zihin://schemas/{schema_type} — containing the exact JSON Schema the server validates with. Recommended flow: read the contract → build schema_data → dry-run with validate_schema_data → create_schema.


Triggers (9 tools)​

ToolCategoryDescription
list_triggersreadList triggers (filters: agent_id, trigger_type, enabled)
get_triggerreadTrigger details
create_triggerwriteCreate trigger (webhook returns callable URL + API Key)
update_triggerwriteUpdate trigger configuration
delete_triggerwriteSoft delete
toggle_triggerwriteEnable/disable
list_trigger_executionsreadExecution history
get_trigger_executionreadExecution details
get_session_trigger_contextreadReverse lookup: given a session_id, returns the trigger and execution that originated the session

Trigger types: webhook, email, schedule


MCP Servers (7 tools)​

Manage external MCP servers connected to agents (not the Zihin MCP Server itself).

ToolCategoryDescription
list_mcp_serversreadList MCP servers for an agent
get_mcp_serverreadMCP server details
create_mcp_serverwriteRegister an external MCP server
update_mcp_serverwriteUpdate configuration
delete_mcp_serverwriteRemove MCP server from agent
test_mcp_serverwriteTest connectivity to an MCP server endpoint (ping + latency)
invalidate_mcp_cachewriteClear cached tools (force reload)

API Keys (5 tools)​

ToolCategoryDescription
list_api_keysreadList tenant API Keys (includes revoked)
get_api_keyreadGet details of a specific API Key
create_api_keywriteCreate API Key with role (anti-escalation enforced)
update_api_keywriteUpdate RPM of an existing API Key
delete_api_keywriteRevoke API Key permanently

Security Policies — CSP (7 tools)​

ToolCategoryDescription
list_cspsreadList security policies
get_cspreadPolicy details
create_cspwriteCreate policy (types: schedule, behavior, data, origin, custom)
update_cspwriteUpdate policy
delete_cspwriteSoft delete
toggle_cspwriteActivate/deactivate
get_effective_cspsreadMerged effective policies for an agent

Scopes (hierarchical): tenant > team > agent > user


Secrets (4 tools)​

ToolCategoryDescription
list_secretsreadList secrets (values never exposed)
create_secretwriteCreate encrypted secret (AES-256-GCM)
update_secretwriteUpdate secret value
delete_secretwriteSoft delete
caution

The plaintext value is shown only once at creation time. Store it immediately.


Introspection and Validation (7 tools)​

ToolCategoryDescription
get_agent_fullreadComplete agent view (schemas + triggers + CSPs)
list_agent_toolsreadAll resolved tools (api_config + MCP + core), with resolved/error status
validate_agent_schemasreadValidate all schemas for an agent
toggle_schemawriteActivate/deactivate a schema
test_triggerwriteSimulate trigger execution with test payload
validate_schema_datareadDry-run: validate schema data without saving — same server-side JSON Schema validation as create_schema/update_schema. Supports all canonical types, including trigger_config and csp_config
get_agent_metricsreadExecution metrics by period (1d, 7d, 30d): LLM calls, errors, success rate, tokens, cost, p50/p95 latency (aggregated server-side — no row cap), tool usage (sampled, with sample_truncated disclosure) and sessions

Budget (3 tools)​

Per-agent spend cap in USD. Unlike the plan's token quota, the budget counts every LLM call — including BYOK.

ToolCategoryDescription
get_agent_budgetreadCurrent cycle balance and effective cap for an agent (unlimited: true = no cap set)
list_agent_budgetsreadBalance/cap of all tenant agents in one batch call
set_agent_budgetwriteSet or remove the cap (limit_usd: null = unlimited). Also the recovery loop: raising the cap lets a budget-stopped agent run again on the next turn

Approvals — HITL (5 tools)​

Human-in-the-loop approval governance: which tool calls require approval (configured per-scope on a CSP) and who approves them (approval policies). The approve/reject decision itself happens in the approver's native chat, not through this API.

ToolCategoryDescription
list_approvalsreadPending approval requests for the tenant. admin/owner see all; editor is scoped to own requests + what they can approve
list_approval_policiesreadApproval policies (filter active_only)
get_approval_policyreadPolicy details (name, stages, approvers, is_active)
create_approval_policywriteCreate a policy. stages[].approvers accepts {type:"user", id} or {type:"role", role}
update_approval_policywriteUpdate name/description/stages or deactivate (is_active: false)

To activate approval for an agent: create the policy, then link it on a CSP via behavior.approval_policy_id + behavior.require_approval_for (array of tool names or { source: "mcp"\|"api"\|"db" } matchers).


Observability (5 tools)​

Aggregated server-side — no row caps.

ToolCategoryDescription
list_executionsreadSearch the tenant's agent executions, most recent first, with pagination (page, limit). Filters: trace_id (the correlation id the integrator sent in metadata.trace_id), session_id, agent_id, status, source (chat, sse, mcp_server, webhook, schedule, email, task, builder, process), start_date/end_date (ISO 8601). Same as GET /api/v1/executions. For one execution's detail use get_execution_diagnostics; for the multi-agent tree, get_execution_trace
get_agent_lineagereadOrchestrator→sub-agent pairs that actually invoked each other (via invoke_agent), with invocation counts — complements allowed_invoke_agents (which is "may invoke")
get_tenant_healthreadTenant-level infra errors not attributable to a specific agent (provider auth, rate limit), grouped by canonical error code
get_execution_tracereadHierarchical multi-agent execution trace from a root_execution_id: supervisor→sub-agents with phases, tool calls and cost per node
get_session_agent_treereadAgent tree of a session (by parent-session lineage): supervisor + sub-agents across all turns — works where per-execution traces can't close the tree in multi-turn sessions

Versioning (8 tools)​

ToolCategoryDescription
list_versionsreadVersion history for a resource
get_versionreadSpecific version details
compare_versionsreadDiff between two versions
rollback_versionwriteRestore resource to a previous version
list_snapshotsreadPublication snapshots for an agent
get_snapshotreadSnapshot details
rollback_snapshotwriteRestore full agent to a publication snapshot
list_agent_historyreadTimeline of all changes to an agent

Tracked resources: agent, schema, trigger, mcp_server

See Versioning for details on how per-resource history and publication snapshots work.


Memory and Scheduler (3 tools)​

ToolCategoryDescription
list_agent_memoryreadList persistent memory entries for an agent
delete_agent_memorywriteDelete a specific memory entry
get_scheduler_statusreadStatus of active scheduled triggers (cron jobs) of the credential's company

Processes (14 tools)​

Process engine: durable multi-step definitions that agents open as instances during a conversation. The engine is enabled per company by Zihin and per process by the admin; a company without the engine sees only get_process_engine_status. Read the zihin://skills/processos skill before working with it.

ToolCategoryDescription
get_process_engine_statusreadWhether the engine is enabled for the tenant
list_process_definitions, get_process_definition, validate_process_definitionreadDefinitions (contract: zihin://schemas/process_definition)
publish_process_definition, retire_process_definitionwriteDefinition lifecycle (the platform computes the next version)
enable_process, disable_processwriteRelease/withdraw a process for the company
list_process_instances, get_process_instance, get_process_trailreadInstances opened by agents; variables and trail only for admin/owner
cancel_process_instance, resolve_process_incidentconsumer-opsOperator interventions (admin/owner). Return a command_id with status received
get_process_commandread (admin/owner)Outcome of an intervention command: received (not applied yet), applied or rejected (with reason). Query this instead of repeating the mutation

Integrations (7 tools)​

An integration is an outbound destination a company owns, with the credential its calls carry. A grant lets another company — or one agent of it — use that integration. Since backend 2026.11.13 the runtime refuses any call that uses an integration's credential — API tools bound to an integration and MCP servers with auth_method: "tunnel" — unless the integration's owner has an active grant for the caller (own use needs no grant). An API tool gets OUTBOUND_NOT_AUTHORIZED; an MCP server whose connection is refused does not load its tools and shows status: "error", and a tool call refused on an open connection fails with OUTBOUND_NOT_AUTHORIZED.

ToolCategoryDescription
list_integrationsreadIntegrations this company owns (items, total)
list_integration_grantsreadGrants where this company is the owner (as: "owner", what it gives) or the consumer (as: "consumer", the default — what it receives)
create_integrationwriteRegister an integration: kind (tunnel, api, mcp), name, target, shareable, limits. target and limits are immutable — to change them, create another integration. For tunnel, target is { service } (the service name declared in the tunnel agent) and the integration is created ready to use: the platform attaches the tunnel credential, so do not call attach_integration_credential
attach_integration_credentialwriteAttach a credential from the company's own vault: integration_id, secret_ref (secret name; the platform/ namespace is reserved) and auth_kind (bearer, api_key, tunnel). One credential per integration; it cannot be replaced afterwards. Not for tunnel integrations — the call is refused with VALIDATION_ERROR: they are created with the platform credential, and the key of the service behind the tunnel belongs in the tunnel agent configuration (inject_headers)
grant_integrationwriteGive a consumer access: integration_id, consumer_tenant_id, optional consumer_agent_id (absent = the whole company), allowed_operations (absent or empty = all operations) and expires_at (ISO 8601). The grant is created active and applies on the consumer's next call
ratify_integration_grantwriteConfirm a provisional grant (pending_ratification → active), e.g. one registered by a migration. Repeating it on an active grant returns the grant unchanged
revoke_integration_grantwriteRevoke a grant. Takes effect on the next call. A revoked grant cannot be reactivated — grant again instead. Repeating it returns the grant unchanged

Who can do what. Reads need integrations:read (owner, admin, editor). Creating an integration and attaching a credential need integrations:manage (owner, admin). Granting, ratifying and revoking need integrations:grant, which only the owner has: an admin key lists these tools (they are builder-write) but the call returns INSUFFICIENT_PERMISSIONS. Only the company that owns the integration can grant, ratify or revoke its grants. A signed-in connection cannot create, credential, grant or ratify; an owner signed in can still revoke.

What a working integration needs today. Grant enforcement covers integrations of kind: "tunnel"; calls through an integration of another kind are refused. A tunnel integration locks its destination to {target.origin}/t/{owner_tenant_id}/{target.service}/…, and a tool or MCP server that points elsewhere is refused.

  • target.service (required) is the service name declared in the tunnel agent (services[].name in zihin-agent.yml). It must be a single path segment that a URL keeps exactly as written: no /, \, ?, #, spaces, %, accented or other non-ASCII characters, and not . or ... Any other name the tunnel agent accepts works (for example _crm, crm:v2, crm@v2). Otherwise create_integration returns VALIDATION_ERROR.
  • target.origin is optional. Omitted, the platform fills it with the tunnel origin (https://tunnel.zihin.ai); if you send it, it must be that origin, or the call returns VALIDATION_ERROR.
  • Credential. Since backend 2026.11.17 a tunnel integration is created with the platform tunnel credential already attached — the response carries credential: { "custody": "platform", "auth_kind": "tunnel" }. Nothing else is needed to use it. The tunnel edge only accepts the platform credential, so attach_integration_credential on a tunnel integration is refused. The key your internal service expects stays in the tunnel agent, in the service's inject_headers in zihin-agent.yml, and is never sent to Zihin.
  • Tunnel integrations created before 2026.11.17 that have no platform credential cannot be fixed in place (target is immutable): every call through them is refused. Create a new tunnel integration and point the MCP server (or API tool) to it with integration_id.

Binding a tool to an integration. Set editor_schema.api.integration_id in an api_config schema, or integration_id on an MCP server (top level, not inside config). A bound tool is authorized by the integration instead of its own auth.secret_ref. On MCP servers, the binding applies with auth_method: "tunnel"; a tunnel MCP server without one is refused.

Operation names in allowed_operations are matched exactly. API tools: "<METHOD> <path>", e.g. "GET /t/<owner>/<service>/orders". API paths have no query string, and a trailing slash counts. MCP servers: the tool name for tools/call and the JSON-RPC method otherwise — a restricted list must also include server/discover and tools/list, and, for servers on the 2025 protocol, initialize, notifications/initialized and ping, or the server cannot connect or fails its health checks.

Expiry. After expires_at the runtime treats the grant as absent, but its status stays active — and it still blocks a new grant with the same scope (the whole company, or the same agent) until it is revoked.

Connecting an MCP server through the Zihin Tunnel​

  1. Declare the service in the tunnel agent. Add it to services in zihin-agent.yml, with the internal URL and, in inject_headers, the key your service expects. See Tunnel — Getting Started.
  2. Create the tunnel integration (owner or admin): create_integration with kind: "tunnel", a name and target: { "service": "<service name>" }. It is created ready to use — do not attach a credential.
  3. Create the MCP server for the agent with auth_method: "tunnel", integration_id set to the integration's id, and endpoint https://tunnel.zihin.ai/t/{tenant_id}/{service}/mcp — your company's id and the same service name (the path after the service is the one your MCP service serves).
  4. Test with test_mcp_server: the server connects and lists its tools.

For another company to use it, the owner of the integration grants access with grant_integration; the other company then creates its own MCP server with auth_method: "tunnel", the same integration_id and the same endpoint — with the owner's company id in the path.

REST​

The same operations are available over REST under /api/v1/integrations, with the same permissions:

MethodPathTool
GET/api/v1/integrationslist_integrations
POST/api/v1/integrationscreate_integration
POST/api/v1/integrations/{id}/credentialattach_integration_credential
GET/api/v1/integrations/grants?as=owner or ?as=consumerlist_integration_grants
POST/api/v1/integrations/{id}/grantsgrant_integration
POST/api/v1/integrations/grants/{grantId}/ratifyratify_integration_grant
POST/api/v1/integrations/grants/{grantId}/revokerevoke_integration_grant
GET/api/v1/integrations/usage— (REST only, see below)

Responses use the standard envelope; lists come as data.items with meta.total. Integrations come with their own name; grants carry ids only — no company or agent names.

Usage log​

GET /api/v1/integrations/usage lists the calls the runtime authorized or refused through integrations, newest first. It needs integrations:read (owner, admin, editor) and is REST only — there is no MCP tool for it.

ParameterDescription
asowner — usage of the integrations this company owns, by every consumer; consumer (default) — usage made by this company
integration_idOnly this integration (UUID). In the owner view, an integration this company does not own returns NOT_FOUND
outcomeauthorized or denied
since, untilInclusive bounds on the call time. Date and time in ISO 8601 with a time zone, up to microseconds (e.g. 2026-11-09T12:00:00Z); a date alone is a VALIDATION_ERROR
limit1–100, default 50
beforeOpaque cursor: pass the meta.next_before of the previous page

Each item has id, integration_id, consumer_tenant_id, consumer_agent_id, grant_id, destination, operation, outcome, reason, bytes and created_at. meta carries as, has_more and next_before (null on the last page).

  • reason is null for a completed call. A refusal (denied) gives why: no_active_grant, destination_mismatch, operation_not_allowed, no_credential, credential_unavailable, integration_not_found, kind_unsupported, target_incomplete, destination_unparseable, platform_ref_unsupported or no_caller. An authorized call that did not complete gives send_failed, transport_error or redirect_refused. Any other value comes as other.
  • In the owner view, destination is always the integration's canonical destination ({origin}/t/{owner}/{service}), never what the consumer tried to reach, and operation is null for a refused attempt — except operation_not_allowed and credential_unavailable, where the destination had already been checked.
  • In the consumer view, destination and operation are what your own configuration called.

Resources​

Read-only data the AI assistant can reference:

URIDescription
zihin://agentsAll agents for the tenant with status, type, tags, and schema types
zihin://schema-templatesReady-to-use examples for each schema type (fields, examples, notes)
zihin://modelsAvailable LLM models with provider, pricing, capabilities, and context window
zihin://schemas/{type}Formal contract (JSON Schema) for each payload type — the exact schema the server validates with. 11 types: api_config, persona_config, skill_config, workflow_config, mcp_tool_config, mcp_resource_config, trigger_config, csp_config, approval_policy, llm_config, process_definition
zihin://skills/{slug}Expert playbooks (7) — see Skills below

Each zihin://schemas/{type} resource also carries an mcp_usage field explaining granularity — critical to avoid contract errors:

  • schema_data types (api_config, persona_config, skill_config, workflow_config, mcp_*): the schema validates exactly the schema_data argument of create_schema/update_schema/validate_schema_data.
  • Entity types (trigger_config, csp_config, approval_policy, process_definition): the schema validates the full record assembled server-side. You only send the tool's input fields — id, tenant_id, timestamps are injected by the server. For example, the trigger_config argument of create_trigger corresponds to properties.trigger_config inside the contract.
  • Field type (llm_config): the schema validates the llm_config argument of create_agent/update_agent. It is a column on the agent, not a schema_data payload, so validate_schema_data does not accept it.

Skills​

Seven procedural playbooks that make the AI assistant a Zihin specialist. Unlike tool descriptions (what each tool does) and formal contracts (payload structure), skills encode multi-tool workflows, decision trees and the gotchas that cause silent failures — e.g. endpoint.name must equal tool_definition.name, or derive session strategy silently creating new sessions when context_mapping doesn't resolve.

SkillCovers
zihin://skills/mcpRouter: category map, RBAC, contract-first workflow, which skill to read next
zihin://skills/criar-agenteFull agent creation: create → persona (canonical format) → validate → publish
zihin://skills/tools-de-agenteAPI and external-MCP tools + the silent-failure rules
zihin://skills/triggers-e-canaisWebhook/schedule/email, session strategy, response formats per channel
zihin://skills/diagnostico7-step debugging decision tree + known failure signatures
zihin://skills/governanca-e-operacaoBudget, CSPs, HITL approvals, human handoff, denylist
zihin://skills/processosProcess engine: create, validate, publish and enable a process definition (including the worker recipe); follow and intervene in the instances agents open

Zero-install: every MCP client already receives the skills as resources — the server's instructions tell the model to read the relevant skill before multi-step flows.

Native install (context-triggered activation): install the skills in your IDE's native format:

# Claude Code (Agent Skills) | Cursor (rules) | Windsurf (rules) | Codex (AGENTS.md index)
ZIHIN_API_KEY=YOUR_API_KEY npx @zihin/mcp-server install-skills --client claude
ZIHIN_API_KEY=YOUR_API_KEY npx @zihin/mcp-server install-skills --client all

Options: --client claude|cursor|windsurf|codex|all · --dir <project-root> · --global (claude only, installs to ~/.claude/skills) · --bundled (offline, uses the copies shipped in the npm package). Skills are fetched from the live server by default, so a fresh install is current. Installed copies are plain files and do not update themselves — see Updating.

For Claude Code, the plugin installs the MCP server and the skills together.


Tool Annotations​

Every tool ships MCP ToolAnnotations, which clients use to calibrate their permission UX:

HintMeaning in Zihin
readOnlyHintReads only — safe to auto-approve. All list_*/get_*/validate_*/compare_* tools. Note: chat_with_agent is not read-only (it executes the agent)
destructiveHintdelete_*, rollback_*, cancel_agent_turn and clear_session — clients should ask for confirmation
idempotentHintupdate_*, set_*, publish_agent, invalidate_mcp_cache, archive_session/unarchive_session — repeating with the same arguments has no additional effect
openWorldHintTools that reach systems outside Zihin: chat_with_agent, test_trigger, test_mcp_server, send_manual_message, invalidate_mcp_cache

Guided Prompts​

Step-by-step workflows the AI assistant can follow. Prompts are offered to owner, admin and editor (not to member). When you sign in with your Zihin account, configure-webhook is not offered (creating triggers is left out of the login), and the steps of setup-agent and add-tool that need a tool left out of the login (MCP server, webhook, secret) tell you to do them in the Zihin console.

PromptArgumentsDescription
setup-agentname, type (assistant, chatbot, workflow, classifier, orchestrator)Complete wizard: create agent, configure persona, add tools, publish, optionally set up webhook
add-toolagent_id, tool_type (api_config)Guide to add a tool with validation rules (endpoint naming, path params, auth setup)
configure-webhookagent_idAPI Key only. Set up webhook trigger: query extraction, response format, session strategy, buffer/split config

Usage Examples​

Create an Agent with Guided Prompt​

In Claude Desktop or Claude Code, select the setup-agent prompt:

  1. Provide a name and type (e.g., data_analyst)
  2. The wizard guides you through:
    • Defining the agent's persona and system prompt
    • Selecting the LLM model and temperature
    • Adding tools (APIs or MCP servers)
    • Publishing the agent

Database access​

The tenant database feature (connections, db_config schemas and the db_event trigger) was removed from the MCP Server on 2026-10-03. To give an agent access to a database, expose the data through an HTTP API and add it as an api_config tool, or connect your own MCP server to the agent.

Validate Before Publishing​

Use introspection tools to verify your agent configuration:

1. get_agent_full → Review complete agent config
2. validate_agent_schemas → Check for errors in all schemas
3. list_agent_tools → See all resolved tools available at runtime
4. validate_schema_data → Dry-run validation for a specific schema
5. test_trigger → Execute a trigger with test payload
6. publish_agent → Publish when everything checks out

Limits and Configuration​

SettingValue
MCP servers per agent10 (max)
MCP tool cache5-minute TTL
Health check interval60 seconds
Tool call timeout30 s by default; per server with config.call_timeout_ms (1–120 s). The agent turn deadline still applies
Connection timeout30 s by default (connection + tool listing); per server with config.timeout (1–120 s)
Secrets encryptionAES-256-GCM
Session TTL by planfree: 24h, basic/pro: 7d, enterprise: 30d

Error Handling​

Every tool returns JSON in content[0].text and the same object in structuredContent (MCP 2025-06-18+). Ten tools (whoami, list_published_agents, list_agents, get_agent, chat_with_agent, list_agent_sessions, get_session_history, validate_schema_data, get_execution_diagnostics, get_agent_metrics) also declare an outputSchema, so clients can validate structuredContent.

Success is { "success": true, ...fields }:

{
"content": [{ "type": "text", "text": "{\"success\":true,\"tenant_id\":\"...\",\"role\":\"admin\"}" }],
"structuredContent": { "success": true, "tenant_id": "...", "role": "admin" }
}

Business errors return isError: true with error as an object that carries a code:

{
"content": [
{
"type": "text",
"text": "{\"success\":false,\"error\":{\"code\":\"NOT_FOUND\",\"message\":\"Agente não encontrado\"}}"
}
],
"structuredContent": {
"success": false,
"error": { "code": "NOT_FOUND", "message": "Agente não encontrado" }
},
"isError": true
}

Depending on the origin, error may carry extra fields next to code and message: details, errors/validation (schema validation), reason, status, current_version (optimistic lock). Branch on error.code, never on the message text.

CodeMeaning
VALIDATION_ERRORInvalid arguments or payload (schema_data, trigger_config, offset not a multiple of limit, invalid dates…)
NOT_FOUNDResource not found or not visible to this key (also used when a member asks for a conversation that is not theirs)
CONFLICTState conflict: resuming a session of another person, unarchiving a session that was not archived, stale version
INSUFFICIENT_PERMISSIONSThe key's role cannot perform the operation (e.g. get_process_command or provenance reads below admin/owner)
UNAUTHORIZEDThe key has no identity for this operation (e.g. a member key without an owner)
PLAN_LIMIT_REACHEDThe tenant's plan does not allow the operation (e.g. create_agent beyond the plan's agent limit)
SESSION_BUSYA turn is already running on that session (chat_with_agent, clear_session) — wait and retry
IDEMPOTENCY_CONFLICTThe same client_message_id was already used with a different message — generate a new id
TURN_TIMEOUTchat_with_agent: the turn exceeded the runtime deadline (timeout_ms or the channel's own) and ended without an answer; comes with session_id and execution_id for get_execution_diagnostics
SERVICE_UNAVAILABLEA dependency is down, or a read failed (e.g. the session lock without Redis, a lookup that could not be completed) — it is not "not found"; retry later
INTERNAL_ERRORUnexpected internal failure. The message carries no database detail — retry, and contact support with the request time if it persists
ERRORGeneric failure without a specific code

Exception — invalid arguments. When the arguments do not match the tool's input schema, the server rejects the call before the tool runs. The result has isError: true and a text starting with Input validation error: …, with no structuredContent and no error.code. Treat it as VALIDATION_ERROR.

chat_with_agent failures carry as code the turn outcome when there is one (QUOTA_EXCEEDED, BUDGET_EXCEEDED, CONTEXT_LIMIT, CANCELLED…), the same vocabulary as the done event of the SSE stream, plus the session_id.

Transport-level failures (missing, invalid or revoked credential, no access to the company) are not tool results: the HTTP transport answers 401/403/503/404 before the JSON-RPC layer — see Transport errors. The stdio proxy prints the cause in its startup banner.


Requirements​

  • Node.js >= 20
  • Compatible with macOS, Linux, and Windows

Source Code​

The @zihin/mcp-server package is open source: github.com/zihin-ai/zihin-mcp