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
| Feature | Details |
|---|---|
| Package | @zihin/mcp-server |
| Tools | 113 (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 |
| Resources | 21 (agents, schema-templates, models + 11 formal contracts zihin://schemas/{type} + 7 skills zihin://skills/{slug}) |
| Skills | 7 expert playbooks (create agent, tools, triggers, diagnostics, governance, processes) — served by the server, installable natively per IDE |
| Guided Prompts | 3 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 Annotations | All 113 tools ship MCP ToolAnnotations (read-only/destructive/idempotent/open-world hints + title) |
| Output contract | Every 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 cache | tools/list, prompts/list and resources/list announce ttlMs of 5 minutes (resources/read: 60 s) — clients may cache the catalog |
| Server version | 2.5.0 (serverInfo.version of the remote server; the npm proxy has its own version) |
| Transports | stdio (via npm package) + HTTP Streamable (direct) |
| Authentication | API Key (/mcp and /mcp/t/{tenant_id}) or, for a person, signing in with the Zihin account (/mcp/t/{tenant_id} only) — see Authentication |
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:
| Way | Who it is for | Endpoint |
|---|---|---|
| Sign in with your Zihin account | A 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 company | https://llm.zihin.ai/mcp/t/{tenant_id} |
| API Key | Integrations, 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.
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
| Variable | Required | Description |
|---|---|---|
ZIHIN_API_KEY | Yes | API Key for authentication |
ZIHIN_MCP_URL | No | Override 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.
| Endpoint | Method | Description |
|---|---|---|
/mcp | POST | Process a JSON-RPC request (API Key) |
/mcp/t/{tenant_id} | POST | Same 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.
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 installed | How to update | How 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-skills | Re-run the same install-skills command; it overwrites the copies. | The command prints the source used (fonte: server or fonte: bundled). |
| The Gemini CLI extension | gemini 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
| Channel | Identifier |
|---|---|
| npm | @zihin/mcp-server |
| Official MCP Registry | ai.zihin/mcp-server (npm package + remote endpoint https://llm.zihin.ai/mcp) |
| Claude Code plugin marketplace | zihin-ai/zihin-mcp → zihin@zihin |
| Gemini CLI extension | zihin-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.
| Credential | Accepted on | Role 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} only | The 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.
| Header | Format | Example |
|---|---|---|
X-Api-Key | Direct | X-Api-Key: YOUR_API_KEY |
Authorization | Bearer with zhn_ prefix | Authorization: Bearer YOUR_API_KEY |
| Prefix | Environment |
|---|---|
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):
| Status | When | What the client should do |
|---|---|---|
401 | Credential 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 |
403 | Valid 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 help | Use the URL of a company you belong to |
429 + Retry-After | Rate 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 envelope | Wait the number of seconds in Retry-After, then retry |
503 + Retry-After: 15 | The sign-in check is temporarily unavailable | Retry later; keep the token, do not sign in again |
404 | Path 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:
| Role | Available Tools | Description |
|---|---|---|
owner | 113 (all) | Tenant owner — full access |
admin | 113 (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. |
editor | 59 (consumer + consumer-profile + builder-read) | Read access (own sessions, aggregated profiles, builder reads). Write operations and consumer-ops are not even listed. |
member | 5 (consumer only) | End-user access: identify session, list agents, chat, view own sessions |
| Role | API Key | Signed in with the Zihin account | Company without the process engine (API Key / signed in) |
|---|---|---|---|
owner, admin | 113 | 89 | 100 / 78 |
editor | 59 | 59 | 52 / 52 |
member | 5 | 5 | 5 |
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:
| Category | Count | Operations | Roles |
|---|---|---|---|
consumer | 5 | Identify session, list published agents, chat, sessions | owner, admin, editor, member |
consumer-profile | 3 | Aggregated cross-consumer reads (get_consumer_profile, list_consumers, list_consumer_sessions) | owner, admin, editor |
consumer-ops | 10 | Tenant-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-read | 51 | list_*, get_*, validate_*, compare_* + budget/approval reads + observability + execution search + process definitions/instances + integrations and grants | owner, admin, editor |
builder-write | 44 | create_*, update_*, delete_*, toggle_*, publish_*, rollback_*, clone_*, test_*, set_agent_budget, process definition lifecycle, integrations (create, credential, grant, ratify, revoke) | owner, admin only |
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:
| Group | Tools |
|---|---|
| Credentials | create_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 authority | publish_process_definition, enable_process |
| Governance | create_approval_policy, update_approval_policy, create_csp, update_csp, toggle_csp, delete_csp |
| Integrations shared with other companies | create_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.
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 conversationsA 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 (
adminandowner): 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).
| Tool | Description |
|---|---|
whoami | Identify the current session: tenant name, role, and subscription plan |
list_published_agents | List published agents available for chat |
chat_with_agent | Send 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_sessions | List 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_history | Message 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):
| Field | Who can send it | Behavior |
|---|---|---|
session_id | any role | Resume a conversation. A member key can only resume its own conversations (others are NOT_FOUND) |
client_message_id | any role | UUID 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_ms | any role | Only 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 |
attachments | member key only | Attachments 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_key | admin/owner key | Identity of the end person the integration is speaking for (same as /stream). Resuming a session of another person returns CONFLICT |
consumer_display_name | admin/owner key, with consumer_key | Display name of that person. Applies from now on (profile and the current conversation); closed conversations keep the name of the time |
consumer_channel | admin/owner key, with consumer_key | The 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, metadata | admin/owner key | See 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):
| Field | Meaning |
|---|---|
user_message_id, assistant_message_id | Ids of the two messages written in the conversation record (the same ids the REST API returns) |
blocks | Structured 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_call | Present 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_replay | Echo of the id sent; idempotent_replay: true when the answer was replayed instead of running the agent |
outcome | Outcome 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.
| Argument | Meaning |
|---|---|
session_id | Id returned by chat_with_agent or list_agent_sessions |
limit | Messages per page (default 50, max 100) — the most recent ones before the cursor |
before | Pagination cursor: the next_before returned by the previous page (pass it unchanged) |
| Output field | Meaning |
|---|---|
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_count | Total number of messages of the conversation — only when before is not sent. With before it is null |
messages_before_cursor | Only with before: how many messages exist before the cursor |
has_more, next_before | next_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.
| Tool | Description |
|---|---|
get_consumer_profile | Get aggregated consumer profile (cross-session, cross-agent): display name, channels used, total sessions, total turns, agents interacted, product flags, timestamps |
list_consumers | Paginated 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_sessions | Paginated 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.
| Tool | Description |
|---|---|
set_consumer_denylist | Add 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_control | Change a session's control_mode (engaged, suspended, manual_handoff). When ≠ engaged, the agent loop is bypassed for new messages on that session |
set_engagement_control | End 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_message | Send 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_turn | Cancel 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_session | Clear 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_session | Archive a conversation (leaves the active list; reversible) |
unarchive_session | Bring an archived conversation back to the active list. CONFLICT if it was not archived |
cancel_process_instance | Cancel a running process instance. Returns a command_id with status received — read the outcome with get_process_command |
resolve_process_incident | Resolve an incident of a process instance (same command_id pattern) |
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)
| Tool | Category | Description |
|---|---|---|
list_agents | read | List tenant agents (filters: status, type, include_archived) |
get_agent | read | Agent details with schemas |
create_agent | write | Create agent (model format: provider.model, e.g. openai.gpt-4.1-nano, or auto for intelligent routing) |
update_agent | write | Update agent metadata. Also accepts chat_enabled (boolean) to enable/disable the agent on the native chat channel (chat.zihin.ai) |
delete_agent | write | Archive or hard-delete agent |
clone_agent | write | Clone agent with schemas and optionally triggers |
publish_agent | write | Publish agent (validates all schemas first) |
Schemas (5 tools)
| Tool | Category | Description |
|---|---|---|
list_schemas | read | List schemas for an agent (filters: schema_type, include_inactive) |
get_schema | read | Schema details |
create_schema | write | Create schema with integrated validation |
update_schema | write | Update schema with re-validation |
delete_schema | write | Remove schema |
Schema types: persona_config, api_config, workflow_config, skill_config, mcp_tool_config, mcp_resource_config
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)
| Tool | Category | Description |
|---|---|---|
list_triggers | read | List triggers (filters: agent_id, trigger_type, enabled) |
get_trigger | read | Trigger details |
create_trigger | write | Create trigger (webhook returns callable URL + API Key) |
update_trigger | write | Update trigger configuration |
delete_trigger | write | Soft delete |
toggle_trigger | write | Enable/disable |
list_trigger_executions | read | Execution history |
get_trigger_execution | read | Execution details |
get_session_trigger_context | read | Reverse 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).
| Tool | Category | Description |
|---|---|---|
list_mcp_servers | read | List MCP servers for an agent |
get_mcp_server | read | MCP server details |
create_mcp_server | write | Register an external MCP server |
update_mcp_server | write | Update configuration |
delete_mcp_server | write | Remove MCP server from agent |
test_mcp_server | write | Test connectivity to an MCP server endpoint (ping + latency) |
invalidate_mcp_cache | write | Clear cached tools (force reload) |
API Keys (5 tools)
| Tool | Category | Description |
|---|---|---|
list_api_keys | read | List tenant API Keys (includes revoked) |
get_api_key | read | Get details of a specific API Key |
create_api_key | write | Create API Key with role (anti-escalation enforced) |
update_api_key | write | Update RPM of an existing API Key |
delete_api_key | write | Revoke API Key permanently |
Security Policies — CSP (7 tools)
| Tool | Category | Description |
|---|---|---|
list_csps | read | List security policies |
get_csp | read | Policy details |
create_csp | write | Create policy (types: schedule, behavior, data, origin, custom) |
update_csp | write | Update policy |
delete_csp | write | Soft delete |
toggle_csp | write | Activate/deactivate |
get_effective_csps | read | Merged effective policies for an agent |
Scopes (hierarchical): tenant > team > agent > user
Secrets (4 tools)
| Tool | Category | Description |
|---|---|---|
list_secrets | read | List secrets (values never exposed) |
create_secret | write | Create encrypted secret (AES-256-GCM) |
update_secret | write | Update secret value |
delete_secret | write | Soft delete |
The plaintext value is shown only once at creation time. Store it immediately.
Introspection and Validation (7 tools)
| Tool | Category | Description |
|---|---|---|
get_agent_full | read | Complete agent view (schemas + triggers + CSPs) |
list_agent_tools | read | All resolved tools (api_config + MCP + core), with resolved/error status |
validate_agent_schemas | read | Validate all schemas for an agent |
toggle_schema | write | Activate/deactivate a schema |
test_trigger | write | Simulate trigger execution with test payload |
validate_schema_data | read | Dry-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_metrics | read | Execution 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.
| Tool | Category | Description |
|---|---|---|
get_agent_budget | read | Current cycle balance and effective cap for an agent (unlimited: true = no cap set) |
list_agent_budgets | read | Balance/cap of all tenant agents in one batch call |
set_agent_budget | write | Set 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.
| Tool | Category | Description |
|---|---|---|
list_approvals | read | Pending approval requests for the tenant. admin/owner see all; editor is scoped to own requests + what they can approve |
list_approval_policies | read | Approval policies (filter active_only) |
get_approval_policy | read | Policy details (name, stages, approvers, is_active) |
create_approval_policy | write | Create a policy. stages[].approvers accepts {type:"user", id} or {type:"role", role} |
update_approval_policy | write | Update 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.
| Tool | Category | Description |
|---|---|---|
list_executions | read | Search 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_lineage | read | Orchestrator→sub-agent pairs that actually invoked each other (via invoke_agent), with invocation counts — complements allowed_invoke_agents (which is "may invoke") |
get_tenant_health | read | Tenant-level infra errors not attributable to a specific agent (provider auth, rate limit), grouped by canonical error code |
get_execution_trace | read | Hierarchical multi-agent execution trace from a root_execution_id: supervisor→sub-agents with phases, tool calls and cost per node |
get_session_agent_tree | read | Agent 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)
| Tool | Category | Description |
|---|---|---|
list_versions | read | Version history for a resource |
get_version | read | Specific version details |
compare_versions | read | Diff between two versions |
rollback_version | write | Restore resource to a previous version |
list_snapshots | read | Publication snapshots for an agent |
get_snapshot | read | Snapshot details |
rollback_snapshot | write | Restore full agent to a publication snapshot |
list_agent_history | read | Timeline 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)
| Tool | Category | Description |
|---|---|---|
list_agent_memory | read | List persistent memory entries for an agent |
delete_agent_memory | write | Delete a specific memory entry |
get_scheduler_status | read | Status 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.
| Tool | Category | Description |
|---|---|---|
get_process_engine_status | read | Whether the engine is enabled for the tenant |
list_process_definitions, get_process_definition, validate_process_definition | read | Definitions (contract: zihin://schemas/process_definition) |
publish_process_definition, retire_process_definition | write | Definition lifecycle (the platform computes the next version) |
enable_process, disable_process | write | Release/withdraw a process for the company |
list_process_instances, get_process_instance, get_process_trail | read | Instances opened by agents; variables and trail only for admin/owner |
cancel_process_instance, resolve_process_incident | consumer-ops | Operator interventions (admin/owner). Return a command_id with status received |
get_process_command | read (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.
| Tool | Category | Description |
|---|---|---|
list_integrations | read | Integrations this company owns (items, total) |
list_integration_grants | read | Grants where this company is the owner (as: "owner", what it gives) or the consumer (as: "consumer", the default — what it receives) |
create_integration | write | Register 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_credential | write | Attach 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_integration | write | Give 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_grant | write | Confirm 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_grant | write | Revoke 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[].nameinzihin-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). Otherwisecreate_integrationreturnsVALIDATION_ERROR.target.originis 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 returnsVALIDATION_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, soattach_integration_credentialon a tunnel integration is refused. The key your internal service expects stays in the tunnel agent, in the service'sinject_headersinzihin-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 (
targetis immutable): every call through them is refused. Create a new tunnel integration and point the MCP server (or API tool) to it withintegration_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
- Declare the service in the tunnel agent. Add it to
servicesinzihin-agent.yml, with the internal URL and, ininject_headers, the key your service expects. See Tunnel — Getting Started. - Create the tunnel integration (owner or admin):
create_integrationwithkind: "tunnel", anameandtarget: { "service": "<service name>" }. It is created ready to use — do not attach a credential. - Create the MCP server for the agent with
auth_method: "tunnel",integration_idset to the integration'sid, and endpointhttps://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). - 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:
| Method | Path | Tool |
|---|---|---|
GET | /api/v1/integrations | list_integrations |
POST | /api/v1/integrations | create_integration |
POST | /api/v1/integrations/{id}/credential | attach_integration_credential |
GET | /api/v1/integrations/grants?as=owner or ?as=consumer | list_integration_grants |
POST | /api/v1/integrations/{id}/grants | grant_integration |
POST | /api/v1/integrations/grants/{grantId}/ratify | ratify_integration_grant |
POST | /api/v1/integrations/grants/{grantId}/revoke | revoke_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.
| Parameter | Description |
|---|---|
as | owner — usage of the integrations this company owns, by every consumer; consumer (default) — usage made by this company |
integration_id | Only this integration (UUID). In the owner view, an integration this company does not own returns NOT_FOUND |
outcome | authorized or denied |
since, until | Inclusive 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 |
limit | 1–100, default 50 |
before | Opaque 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).
reasonisnullfor 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_unsupportedorno_caller. Anauthorizedcall that did not complete givessend_failed,transport_errororredirect_refused. Any other value comes asother.- In the
ownerview,destinationis always the integration's canonical destination ({origin}/t/{owner}/{service}), never what the consumer tried to reach, andoperationisnullfor a refused attempt — exceptoperation_not_allowedandcredential_unavailable, where the destination had already been checked. - In the
consumerview,destinationandoperationare what your own configuration called.
Resources
Read-only data the AI assistant can reference:
| URI | Description |
|---|---|
zihin://agents | All agents for the tenant with status, type, tags, and schema types |
zihin://schema-templates | Ready-to-use examples for each schema type (fields, examples, notes) |
zihin://models | Available 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_datatypes (api_config,persona_config,skill_config,workflow_config,mcp_*): the schema validates exactly theschema_dataargument ofcreate_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, thetrigger_configargument ofcreate_triggercorresponds toproperties.trigger_configinside the contract. - Field type (
llm_config): the schema validates thellm_configargument ofcreate_agent/update_agent. It is a column on the agent, not aschema_datapayload, sovalidate_schema_datadoes 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.
| Skill | Covers |
|---|---|
zihin://skills/mcp | Router: category map, RBAC, contract-first workflow, which skill to read next |
zihin://skills/criar-agente | Full agent creation: create → persona (canonical format) → validate → publish |
zihin://skills/tools-de-agente | API and external-MCP tools + the silent-failure rules |
zihin://skills/triggers-e-canais | Webhook/schedule/email, session strategy, response formats per channel |
zihin://skills/diagnostico | 7-step debugging decision tree + known failure signatures |
zihin://skills/governanca-e-operacao | Budget, CSPs, HITL approvals, human handoff, denylist |
zihin://skills/processos | Process 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:
| Hint | Meaning in Zihin |
|---|---|
readOnlyHint | Reads only — safe to auto-approve. All list_*/get_*/validate_*/compare_* tools. Note: chat_with_agent is not read-only (it executes the agent) |
destructiveHint | delete_*, rollback_*, cancel_agent_turn and clear_session — clients should ask for confirmation |
idempotentHint | update_*, set_*, publish_agent, invalidate_mcp_cache, archive_session/unarchive_session — repeating with the same arguments has no additional effect |
openWorldHint | Tools 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.
| Prompt | Arguments | Description |
|---|---|---|
setup-agent | name, type (assistant, chatbot, workflow, classifier, orchestrator) | Complete wizard: create agent, configure persona, add tools, publish, optionally set up webhook |
add-tool | agent_id, tool_type (api_config) | Guide to add a tool with validation rules (endpoint naming, path params, auth setup) |
configure-webhook | agent_id | API 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:
- Provide a name and type (e.g.,
data_analyst) - 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
| Setting | Value |
|---|---|
| MCP servers per agent | 10 (max) |
| MCP tool cache | 5-minute TTL |
| Health check interval | 60 seconds |
| Tool call timeout | 30 s by default; per server with config.call_timeout_ms (1–120 s). The agent turn deadline still applies |
| Connection timeout | 30 s by default (connection + tool listing); per server with config.timeout (1–120 s) |
| Secrets encryption | AES-256-GCM |
| Session TTL by plan | free: 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.
| Code | Meaning |
|---|---|
VALIDATION_ERROR | Invalid arguments or payload (schema_data, trigger_config, offset not a multiple of limit, invalid dates…) |
NOT_FOUND | Resource not found or not visible to this key (also used when a member asks for a conversation that is not theirs) |
CONFLICT | State conflict: resuming a session of another person, unarchiving a session that was not archived, stale version |
INSUFFICIENT_PERMISSIONS | The key's role cannot perform the operation (e.g. get_process_command or provenance reads below admin/owner) |
UNAUTHORIZED | The key has no identity for this operation (e.g. a member key without an owner) |
PLAN_LIMIT_REACHED | The tenant's plan does not allow the operation (e.g. create_agent beyond the plan's agent limit) |
SESSION_BUSY | A turn is already running on that session (chat_with_agent, clear_session) — wait and retry |
IDEMPOTENCY_CONFLICT | The same client_message_id was already used with a different message — generate a new id |
TURN_TIMEOUT | chat_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_UNAVAILABLE | A 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_ERROR | Unexpected internal failure. The message carries no database detail — retry, and contact support with the request time if it persists |
ERROR | Generic 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