Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
ZIHIN_API_KEYYesAPI Key do tenant (formato zhn_live_*, zhn_test_* ou zhn_dev_*)
ZIHIN_MCP_URLNoURL 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

CapabilityDetails
tools
{}
prompts
{}
resources
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 before/limit/next_before (user/assistant messages only; attachments as metadata) — see below

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 last_seen_at (desc). Filters: search (substring in display_name or consumer_key), blocked (true = only denylisted, false = only not-denylisted)

list_consumer_sessionsA

Paginated list of a specific consumer's sessions (cross-agent, most recent first) — complements get_consumer_profile, which returns only aggregated counters

send_manual_messageA

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_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 root_execution_id

set_session_controlB

Change a session's control_mode (engaged, suspended, manual_handoff). When ≠ engaged, the agent loop is bypassed for new messages on that session

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. CONFLICT if it was not archived

list_agentsB

List tenant agents (filters: status, type, include_archived)

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: schema_type, include_inactive)

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: agent_id, trigger_type, enabled)

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 session_id, returns the trigger and execution that originated the session

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 resolved/error status

validate_agent_schemasA

Validate an agent's configured schemas and report errors and warnings before publication.

get_agent_metricsA

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

validate_schema_dataA

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

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 (limit_usd: null = unlimited). Also the recovery loop: raising the cap lets a budget-stopped agent run again on the next turn

list_approvalsA

Pending approval requests for the tenant. admin/owner see all; editor is scoped to own requests + what they can approve

list_approval_policiesC

Approval policies (filter active_only)

get_approval_policyC

Policy details (name, stages, approvers, is_active)

create_approval_policyC

Create a policy. stages[].approvers accepts {type:"user", id} or {type:"role", role}

update_approval_policyA

Update name/description/stages or deactivate (is_active: false)

list_integrationsB

Integrations this company owns (items, total)

list_integration_grantsA

Grants where this company is the owner (as: "owner", what it gives) or the consumer (as: "consumer", the default — what it receives)

create_integrationA

Register an integration: kind (tunnel, api, mcp), name, target, shareable, limits. target and limits are immutable — to change them, create another integration

attach_integration_credentialA

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

grant_integrationA

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_grantA

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_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 invoke_agent), with invocation counts — complements allowed_invoke_agents (which is "may invoke")

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 root_execution_id: supervisor→sub-agents with phases, tool calls and cost per node

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 (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

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: received (not applied yet), applied or rejected (with reason). Query this instead of repeating the mutation

cancel_process_instanceA

Cancel a running process instance. Returns a command_id with status received — read the outcome with get_process_command

resolve_process_incidentC

Resolve an incident of a process instance (same command_id pattern)

get_process_engine_statusB

Whether the engine is enabled for the tenant

Prompts

Interactive templates invoked by user choice

NameDescription
setup-agentCreate an agent with its persona, optional tools and publication, step by step.
add-toolAdd an external API tool (api_config) to an existing agent.
configure-webhookConfigure a webhook trigger so an agent can receive external HTTP requests.

Resources

Contextual data attached and managed by the client

NameDescription
agentsTenant agents with identifiers, names, biography, status, type, visibility, tags and configured schema types.
schema-templatesSchema data templates for persona_config, api_config, workflow_config and skill_config. Create triggers and CSPs with their dedicated tools.
modelsAvailable language models with providers, pricing and capabilities.
schema-api_configFormal JSON Schema validation contract for api_config. Validates schema_data for create_schema, update_schema and validate_schema_data.
schema-persona_configFormal JSON Schema validation contract for persona_config. Validates schema_data.
schema-skill_configFormal JSON Schema validation contract for skill_config. Validates schema_data.
schema-workflow_configFormal JSON Schema validation contract for workflow_config. Validates schema_data.
schema-mcp_tool_configFormal JSON Schema validation contract for mcp_tool_config. Validates schema_data.
schema-mcp_resource_configFormal JSON Schema validation contract for mcp_resource_config. Validates MCP server configuration: connection timeout (config.
schema-trigger_configFormal JSON Schema validation contract for trigger_config. Entity contract: validates the complete server-created trigger.
schema-csp_configFormal JSON Schema validation contract for csp_config. Entity contract: validates a complete CSP record.
schema-approval_policyFormal JSON Schema validation contract for approval_policy. Entity contract: validates a complete approval policy.
schema-process_definitionFormal JSON Schema validation contract for process_definition. Entity contract: validates a process definition.
schema-llm_configFormal 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

B3/5.0

Scored across 113 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count2/5

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.

Completeness3/5

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.

Maintenance

ActivityMaintained
ResponsivenessMixed handling