Zihin MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ZIHIN_API_KEY | Yes | API Key do tenant (formato zhn_live_*, zhn_test_* ou zhn_dev_*) | |
| ZIHIN_MCP_URL | No | URL do MCP Server (default: https://llm.zihin.ai/mcp) | https://llm.zihin.ai/mcp |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Zihin Agent Builder MCP server. Manage AI agents within the tenant selected by the API key or the personal OAuth URL /mcp/t/{tenant_id}. Use whoami to confirm the tenant, role and plan.
Workflows:
Create an agent: setup-agent, or create_agent → create_schema with persona_config → publish_agent. Persona data requires editor_schema.persona.role and objective.
Agent tools: create_schema with api_config for an external API, or create_mcp_server for an external MCP server. endpoint.name must equal tool_definition.name.
Diagnostics: get_agent_metrics, get_tenant_health, get_execution_diagnostics, get_execution_trace and get_session_agent_tree.
Shared integrations: create_integration → attach_integration_credential → grant_integration. Granting, ratifying and revoking require owner; see zihin://skills/governanca-e-operacao.
Governance: set_agent_budget sets a USD spending ceiling; create_csp defines policies; create_approval_policy with behavior.require_approval_for adds human approval. update_agent controls memory_enabled, engagement_control_enabled and quick_replies_enabled. set_engagement_control lets operators close or reopen engagement per consumer. Tool timeouts use editor_schema.api.timeout_ms for APIs and config.call_timeout_ms for MCP.
Rules:
Writes require admin or owner. The available tool list reflects the caller's role and delegation policy. Integration grants require owner; process trails and command outcomes require admin/owner, even when listed for another role.
IDs are UUIDs; discover them through list_* tools before acting.
test_trigger and chat_with_agent execute real agents, consume tokens and may cause external side effects.
Resources: zihin://agents, zihin://schema-templates, zihin://schemas/{type} and zihin://models. Formal schema resources preserve the validation constraints enforced by the server.
Read the matching schema before constructing a payload. Use validate_schema_data for supported schema_data types, or validate_process_definition for processes, before writing. Entity schemas describe complete server records; send only the tool's documented inputs.
Before multi-step work, read the matching guide: zihin://skills/mcp, zihin://skills/criar-agente, zihin://skills/tools-de-agente, zihin://skills/triggers-e-canais, zihin://skills/diagnostico, zihin://skills/governanca-e-operacao or zihin://skills/processos.
Results are JSON in content and structuredContent. A result with success: false and error: { code, message } is a business failure. Branch on code and read message for the next action.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| prompts | {} |
| resources | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| whoamiA | Identify the current session: tenant name, role, and subscription plan |
| list_published_agentsA | List published agents available for chat |
| list_agent_sessionsA | List recent conversations with an agent, newest first; status selects active (default) or archived sessions. Members see their own sessions; operators see tenant sessions. message_count and last_message_preview cover up to 50 recent messages, while total counts all matching sessions. offset must be a multiple of limit. |
| get_session_historyA | Message history of a session, read from the durable record and paginated with |
| chat_with_agentA | Send a message to a published agent. This executes the agent, consumes tokens and may cause external side effects. Reuse session_id for conversation context and client_message_id for idempotent retries. Shared admin/owner integrations must provide consumer_key to enable person-scoped memory. Returns response, execution/session identifiers, usage and structured blocks. See https://docs.zihin.ai/agents/invocation-contract. |
| get_consumer_profileA | Get aggregated consumer profile (cross-session, cross-agent): display name, channels used, total sessions, total turns, agents interacted, product flags, timestamps |
| list_consumersA | Paginated list of consumers, ordered by |
| list_consumer_sessionsA | Paginated list of a specific consumer's sessions (cross-agent, most recent first) — complements |
| send_manual_messageA | Send a manual operator message through the same outbound channel as the agent (Twilio/Meta/webhook). Requires |
| cancel_agent_turnA | 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 |
| set_session_controlB | Change a session's |
| set_consumer_denylistA | 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) |
| clear_sessionA | Irreversibly clear conversation history while preserving the conversation record. Returns SESSION_BUSY during an active turn or SERVICE_UNAVAILABLE when the delivery lock is unavailable. Requires the HTTP backend. |
| archive_sessionA | Archive a conversation (leaves the active list; reversible) |
| unarchive_sessionA | Bring an archived conversation back to the active list. |
| list_agentsB | List tenant agents (filters: |
| get_agentB | Retrieve an agent configuration by UUID within the current tenant. |
| create_agentA | Create a draft agent and return its UUID. Add a persona with create_schema (persona_config), then publish_agent. Returns PLAN_LIMIT_REACHED when the tenant agent limit is reached. Read zihin://skills/criar-agente. |
| update_agentA | Update only the supplied agent fields. memory_enabled, quick_replies_enabled and engagement_control_enabled change the agent tool surface and require admin/owner. chat_enabled controls native chat availability. Inspect partial_update if only part of the update succeeded. |
| delete_agentA | Archive an agent: remove it from listings and stop it responding. Restore through the Zihin console; this server has no restore tool. |
| clone_agentB | Clone agent with schemas and optionally triggers |
| publish_agentB | Publish agent (validates all schemas first) |
| list_schemasC | List schemas for an agent (filters: |
| get_schemaB | Retrieve one agent configuration schema and its current version. |
| create_schemaC | Create schema with integrated validation |
| update_schemaA | Update an agent schema using its current base_version. Supplied schema_data replaces the full document; reload and reconcile on CONFLICT. |
| delete_schemaA | Permanently remove an agent configuration schema. Its behavior or tool will no longer be available to the agent. |
| list_triggersC | List triggers (filters: |
| get_triggerB | Retrieve a trigger and its current configuration before inspection or update. |
| create_triggerA | Create a webhook, schedule or email trigger. Read zihin://schemas/trigger_config and use its exact enums. The server supplies tenant and record identifiers. The returned call block contains method, URL and authentication instructions; it does not return the API key value. Read zihin://skills/triggers-e-canais. |
| update_triggerA | Update only supplied trigger fields. trigger_config replaces the entire configuration; read get_trigger first and include all settings to retain. |
| delete_triggerA | Permanently remove a trigger and stop its configured automation. |
| toggle_triggerA | Enable or disable a trigger without deleting its configuration. Set enabled for the desired state; omitting it toggles the current state. Concurrent calls can race, so verify the returned is_active value. |
| list_trigger_executionsB | List execution records for a trigger to inspect recent runs and delivery results. |
| get_trigger_executionA | Retrieve one trigger execution and its recorded outcome for troubleshooting. |
| get_session_trigger_contextB | Reverse lookup: given a |
| list_mcp_serversB | List the external MCP servers configured for an agent. |
| get_mcp_serverA | Retrieve an external MCP server configuration by its UUID. |
| create_mcp_serverA | Register an external MCP server for an agent. Use http (Streamable HTTP) or stdio (local development). Authentication: none; bearer with config.vault_secret_id; api_key with vault_secret_id and optional api_key_header; tunnel uses platform authentication. timeout controls connection and tool discovery; call_timeout_ms controls each tool call (1000–120000 ms, default 30000). Timed-out calls are not retried automatically. Read zihin://schemas/mcp_resource_config for headers and defaults_from_context. |
| update_mcp_serverA | Update only supplied MCP server fields. config replaces the whole object; send all settings to retain. Changes invalidate the agent tool surface; connection, configuration, authentication and transport changes also invalidate server tool discovery. |
| delete_mcp_serverA | Permanently remove an external MCP server from the agent configuration. |
| test_mcp_serverA | Perform a real MCP handshake and list external tools to check connectivity, authentication and protocol compatibility. Updates the stored server status, last error and protocol version. success=true means the test ran; reachable is its result. Inspect error_class and error_message when unreachable. |
| invalidate_mcp_cacheA | Invalidate cached discovery for an external MCP server after its available tools change. |
| list_api_keysA | List tenant API key metadata without exposing secret key values. |
| create_api_keyB | Create API Key with role (anti-escalation enforced) |
| get_api_keyA | Retrieve metadata for a tenant API key. The secret key value is not returned. |
| update_api_keyB | Update the supplied API key settings within the caller's permissions and tenant plan limits. |
| delete_api_keyA | Revoke a tenant API key. Requests using that credential will no longer be authorized. |
| list_cspsB | List contextual security policies in the current tenant. |
| get_cspA | Retrieve one contextual security policy and its configured rules. |
| create_cspA | Create a contextual security policy with tenant, team, agent or user scope. Read zihin://schemas/csp_config: unknown rule fields may be accepted but have no effect. behavior.must_not_tools blocks named tools; execution ceilings use max_iterations, max_tool_calls and max_tokens_per_request. Native-chat human approval uses require_approval_for with tool names or matchers (tool_name, mcp_server_id, source=mcp|api) and approval_policy_id. Data rules are model instructions, not programmatic masking. origin policies are stored but not enforced; never use them as an access-control boundary. Custom rules become prompt instructions. See zihin://skills/governanca-e-operacao for examples. |
| update_cspA | Update a contextual security policy. Supplied rules replace the whole object; include all fields to retain. Check zihin://schemas/csp_config because unknown fields may be accepted without effect. Use behavior.must_not_tools for tool restrictions and require_approval_for with approval_policy_id for native-chat human approval. |
| delete_cspA | Permanently remove a contextual security policy and immediately remove its restrictions. Use toggle_csp to suspend it reversibly. |
| toggle_cspA | Enable or disable a contextual security policy. Inactive policies are not applied. Set enabled for the desired state; omitting it toggles the current state. Concurrent calls can race, so verify the returned is_active value. |
| get_effective_cspsC | Inspect the contextual security policies effective for the requested scope. |
| get_agent_fullB | Complete agent view (schemas + triggers + CSPs) |
| list_agent_toolsC | All resolved tools (api_config + MCP + core), with |
| validate_agent_schemasA | Validate an agent's configured schemas and report errors and warnings before publication. |
| get_agent_metricsA | Execution metrics by period ( |
| validate_schema_dataA | Dry-run: validate schema data without saving — same server-side JSON Schema validation as |
| toggle_schemaA | Enable or disable a schema without deleting it. Inactive schemas are not loaded by the agent. Set enabled for the desired state; omitting it toggles the current state. Concurrent calls can race, so verify the returned is_active value. |
| test_triggerA | Execute a trigger with a test payload. This runs the agent, consumes tokens and may cause external side effects. |
| get_execution_diagnosticsA | Get execution diagnostics: chronological model and tool calls, tokens, latency, model, finish_reason, cache reads/writes and caller correlation metadata. Use the execution_id or root_execution_id returned by chat_with_agent. |
| list_secretsA | List tenant secret metadata without exposing credential values. Use each name as secret_ref where supported. |
| create_secretA | Create an encrypted tenant secret. Save its value before submitting; plaintext is not returned afterward. Reference its name as secret_ref in API tools, MCP servers and trigger callbacks. Names starting with platform/ are reserved. |
| update_secretA | Replace a tenant secret value with a newly encrypted value. Existing references keep using the same secret name. |
| delete_secretA | Permanently delete a tenant secret. API tools, MCP servers and trigger callbacks that reference it will stop working. |
| list_versionsA | List recorded versions of a configuration resource for inspection or rollback. |
| get_versionA | Retrieve one recorded resource version for inspection before restoring it. |
| compare_versionsB | Compare two recorded versions of a configuration resource and inspect their changes. |
| rollback_versionB | Restore a resource from a recorded version, replacing its current configuration. |
| list_agent_historyA | List an agent's recorded change history to investigate configuration changes. |
| list_snapshotsB | List an agent's publication snapshots available for inspection or restoration. |
| get_snapshotA | Retrieve a publication snapshot and inspect its saved configuration before restoration. |
| rollback_snapshotA | Restore an agent from a previous publication snapshot, overwriting its current configuration, schemas, triggers and MCP servers. Inspect get_snapshot before restoring. |
| list_agent_memoryC | List persistent memory entries for an agent |
| delete_agent_memoryA | Delete one persistent agent memory. Platform control entries are protected and cannot be removed here. |
| get_scheduler_statusC | Status of active scheduled triggers (cron jobs) |
| set_engagement_controlA | 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 |
| get_agent_budgetA | Get the current agent spending cap and cycle balance in USD. Includes all model calls, including BYOK; unlimited=true means no cap. |
| list_agent_budgetsA | Get current USD spending caps and balances for all tenant agents in one call. Includes BYOK usage. |
| set_agent_budgetA | Set or remove the cap ( |
| list_approvalsA | Pending approval requests for the tenant. |
| list_approval_policiesC | Approval policies (filter |
| get_approval_policyC | Policy details (name, stages, approvers, |
| create_approval_policyC | Create a policy. |
| update_approval_policyA | Update name/description/stages or deactivate ( |
| list_integrationsB | Integrations this company owns ( |
| list_integration_grantsA | Grants where this company is the owner ( |
| create_integrationA | Register an integration: |
| attach_integration_credentialA | Attach a credential from the company's own vault: |
| grant_integrationA | Give a consumer access: |
| ratify_integration_grantA | Confirm a provisional grant ( |
| revoke_integration_grantA | Revoke a grant. Takes effect on the next call. A revoked grant cannot be reactivated — grant again instead. Repeating it returns the grant unchanged |
| get_agent_lineageA | Orchestrator→sub-agent pairs that actually invoked each other (via |
| get_tenant_healthA | Tenant-level infra errors not attributable to a specific agent (provider auth, rate limit), grouped by canonical error code |
| get_execution_traceB | Hierarchical multi-agent execution trace from a |
| get_session_agent_treeA | 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 |
| list_executionsA | Search the tenant's agent executions, most recent first, with pagination ( |
| list_process_definitionsA | List the latest published definition for each process key in the tenant, including its version, steps and availability to agents. Agents open instances with open_process. |
| get_process_definitionA | Get a complete process definition and its version history. Omit version for the latest published version; inspect it before publishing a new one. |
| validate_process_definitionA | Validate a process definition without saving: structure, execution rules and tenant ownership of referenced agents, approval policies and MCP servers. Returns errors with paths and reasons. Run before publishing. |
| publish_process_definitionA | Publish the next version of a process definition. New instances use it; existing instances retain their original version. Validate first. Worker request recipes belong to the definition; agents select among its allowed recipes. |
| retire_process_definitionA | Retire all published versions of a process key to prevent new instances. Existing instances continue. Publish a new version to make the process available again. |
| enable_processA | Allow agents in this tenant to open a published process, or use * for all published processes. Takes effect immediately on this replica without restarting. |
| disable_processA | Remove permission to open new instances of a process, or use * for all. Existing instances continue. Permissions provided by server configuration cannot be removed here. |
| list_process_instancesA | List tenant process instances, newest first, with status, current step and owner. Filter by open/closed state or definition; use get_process_instance for details. |
| get_process_instanceA | Inspect a process instance. Editors see status, steps, agent, name and dates. Admin/owner roles also see redacted variables, human tasks, file metadata and computation summaries. |
| get_process_trailA | Read a process instance audit trail in order, including transitions, triggering events/commands and reasons. Sensitive values are redacted. Requires admin or owner. |
| get_process_commandA | Outcome of an intervention command: |
| cancel_process_instanceA | Cancel a running process instance. Returns a |
| resolve_process_incidentC | Resolve an incident of a process instance (same |
| get_process_engine_statusB | Whether the engine is enabled for the tenant |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| setup-agent | Create an agent with its persona, optional tools and publication, step by step. |
| add-tool | Add an external API tool (api_config) to an existing agent. |
| configure-webhook | Configure a webhook trigger so an agent can receive external HTTP requests. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| agents | Tenant agents with identifiers, names, biography, status, type, visibility, tags and configured schema types. |
| schema-templates | Schema data templates for persona_config, api_config, workflow_config and skill_config. Create triggers and CSPs with their dedicated tools. |
| models | Available language models with providers, pricing and capabilities. |
| schema-api_config | Formal JSON Schema validation contract for api_config. Validates schema_data for create_schema, update_schema and validate_schema_data. |
| schema-persona_config | Formal JSON Schema validation contract for persona_config. Validates schema_data. |
| schema-skill_config | Formal JSON Schema validation contract for skill_config. Validates schema_data. |
| schema-workflow_config | Formal JSON Schema validation contract for workflow_config. Validates schema_data. |
| schema-mcp_tool_config | Formal JSON Schema validation contract for mcp_tool_config. Validates schema_data. |
| schema-mcp_resource_config | Formal JSON Schema validation contract for mcp_resource_config. Validates MCP server configuration: connection timeout (config. |
| schema-trigger_config | Formal JSON Schema validation contract for trigger_config. Entity contract: validates the complete server-created trigger. |
| schema-csp_config | Formal JSON Schema validation contract for csp_config. Entity contract: validates a complete CSP record. |
| schema-approval_policy | Formal JSON Schema validation contract for approval_policy. Entity contract: validates a complete approval policy. |
| schema-process_definition | Formal JSON Schema validation contract for process_definition. Entity contract: validates a process definition. |
| schema-llm_config | Formal JSON Schema validation contract for llm_config. Field contract: validates llm_config in create_agent and update_agent, not schema_data. |
| skill-criar-agente | [Skill] Use this guide to create, configure, validate and publish a hosted Zihin agent, including its persona, tools, channels and optional memory settings. |
| skill-diagnostico | [Skill] Use this guide to investigate incorrect agent responses, missing tools, failed runs, high cost or latency, and conversations that no longer start new turns. |
| skill-governanca-e-operacao | [Skill] Use this guide to manage agent budgets, contextual security policies, human approval, operator handoff, consumer restrictions and recovery from operational blocks. |
| skill-mcp | [Skill] Use this guide when starting work with the Zihin MCP server to discover account permissions, current schemas and the appropriate task-specific guide. |
| skill-processos | [Skill] Use this guide to validate, publish and enable process definitions, configure worker recipes, inspect running instances and resolve permitted process incidents. |
| skill-tools-de-agente | [Skill] Use this guide when adding external API or MCP capabilities to a Zihin agent, configuring authentication, validating tools or restricting their availability. |
| skill-triggers-e-canais | [Skill] Use this guide to connect an agent to webhooks, schedules or email, choose session and response behavior, and validate delivery to the intended external channel. |
TDQS
Scored across 113 tools
Most tools have a clear resource+action identity and the descriptions are unusually detailed, which helps a lot. However, several clusters overlap enough to cause misselection: list_versions/get_version/compare_versions/rollback_version vs list_snapshots/get_snapshot/rollback_snapshot vs list_agent_history, and list_agents vs list_published_agents vs get_agent vs get_agent_full. Session-oriented tools (list_agent_sessions, list_consumer_sessions, list_executions, get_session_history, get_session_agent_tree) also require careful reading to distinguish.
The dominant pattern is consistent snake_case verb_noun (list_agents, create_trigger, delete_csp, update_mcp_server), applied across the large majority of the surface. Deviations are minor: whoami (no verb), get_agent_full, get_effective_csps, invalidate_mcp_cache, and enable_process/disable_process sitting alongside the toggle_* family.
113 tools is far beyond a comfortable surface for an agent to select from, even granting that the platform genuinely spans agents, schemas, triggers, MCP servers, CSPs, secrets, budgets, approvals, integrations, executions and processes. Several tools are near-redundant conveniences (get_agent_budget vs list_agent_budgets, get_agent vs get_agent_full, get_version vs get_snapshot) that suggest the set should be consolidated or split into sub-servers.
Coverage is broad and lifecycle-oriented in most areas (agents, schemas, triggers, MCP servers, CSPs, secrets, versions, processes), but there are real dead ends: list_approvals has no approve/reject tool, approval policies have CRUD minus delete, agent memory can be listed and deleted but not created, integrations have create/grant/revoke but no update or delete, and delete_agent explicitly has no restore counterpart in this server.