MCP Server

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

Overview

Feature	Details
Package	`@zihin/mcp-server`
Tools	72 (4 consumer + 32 builder-read + 36 builder-write)
Resources	3 (agents, schema-templates, models)
Guided Prompts	3 (setup-agent, add-tool, configure-webhook)
Transports	stdio (via npm package) + HTTP Streamable (direct)

Setup

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

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"

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	Initialize session or process JSON-RPC request
`/mcp`	GET	SSE stream for server notifications
`/mcp`	DELETE	Close session

Responses are returned as text/event-stream (SSE). The mcp-session-id is returned in the response header of the initialize call — use it in all subsequent requests.

Required Headers

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

Initialize a session:

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": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0" }
    }
  }'

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" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_agents",
      "arguments": { "status": "published" }
    }
  }'

Authentication

The MCP Server uses the 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. All operations are automatically scoped to the key's tenant.

Role-Based Access Control (RBAC)

Each API Key has a role that controls which tools are available. See API Keys - Role System for how to create keys with specific roles.

Role	Available Tools	Description
`owner`	72 (all)	Tenant owner — full access
`admin`	72 (all)	Full access: consumer + builder-read + builder-write. Default for new keys.
`editor`	36 (consumer + builder-read)	Read-only builder access, write operations blocked by factory + guard
`member`	4 (consumer only)	End-user access: list agents, chat, view sessions

Tool categories:

Category	Count	Operations	Roles
`consumer`	4	List published agents, chat, sessions	owner, admin, editor, member
`builder-read`	32	`list_`, `get_`, `validate_`, `compare_`	owner, admin, editor
`builder-write`	36	`create_`, `update_`, `delete_`, `toggle_`, `publish_`, `rollback_`, `clone_`, `test_`	owner, admin only

Defense-in-Depth

RBAC is enforced in two layers: (1) the factory only registers tools allowed for the role (editor doesn't see write tools), and (2) a server-side guard blocks write operations for non-admin/owner roles even if the tool is registered.

Anti-escalation

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

Tools Reference

Consumer (4 tools)

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

Tool	Description
`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`)
`list_agent_sessions`	List recent sessions for an agent
`get_session_history`	Get message history for a session (user/assistant messages only)

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.

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
`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, db_config, knowledge, workflow_config, policy

Dry-Run Validation

Use validate_schema_data (in the Introspection section) to validate a schema without saving it.

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, db_event, email, schedule

Connections (6 tools)

Tool	Category	Description
`list_connections`	read	List database connections
`get_connection`	read	Connection details (secrets masked)
`create_connection`	write	Create connection (providers: `postgresql`, `supabase`)
`update_connection`	write	Update configuration
`delete_connection`	write	Soft delete
`test_connection`	write	Test database connectivity

Connection Schema (3 tools)

Tool	Category	Description
`get_connection_schema`	read	Database schema via cache (tables, columns, types)
`get_connection_semantic`	read	Semantic context (domains, keywords, entities)
`refresh_connection_schema`	write	Re-introspect database and update cache

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

caution

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 + db_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
`get_agent_metrics`	read	Execution metrics by period (`1d`, `7d`, `30d`)

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.

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 templates for each schema type (fields, examples, notes)
`zihin://models`	Available LLM models with provider, pricing, capabilities, and context window

Guided Prompts

Step-by-step workflows the AI assistant can follow:

Prompt	Arguments	Description
`setup-agent`	`name`, `type` (assistant, chatbot, workflow, classifier)	Complete wizard: create agent, configure persona, add tools, publish, optionally set up webhook
`add-tool`	`agent_id`, `tool_type` (api_config, db_config)	Guide to add a tool with validation rules (endpoint naming, path params, auth setup)
`configure-webhook`	`agent_id`	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 (database queries, APIs, or MCP servers)
- Publishing the agent

Add a Database Tool

Using the add-tool prompt with tool_type: db_config:

Select a connection from list_connections
Explore the schema with get_connection_schema
Define the query template with parameter placeholders ($1, $2)
Map parameters from the agent's input schema

Validate Before Publishing

Use introspection tools to verify your agent configuration:

get_agent_full         → Review complete agent config
validate_agent_schemas → Check for errors in all schemas
list_agent_tools       → See all resolved tools available at runtime
validate_schema_data   → Dry-run validation for a specific schema
test_trigger           → Execute a trigger with test payload
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 seconds
Connection timeout	10 seconds
Secrets encryption	AES-256-GCM
Session TTL by plan	free: 24h, basic/pro: 7d, enterprise: 30d

Error Handling

Tool errors return an object with isError: true:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\":false,\"error\":\"Agent not found\",\"code\":\"NOT_FOUND\"}"
    }
  ],
  "isError": true
}

Code	Description
`MISSING_API_KEY`	`X-Api-Key` header missing
`INVALID_API_KEY`	API Key invalid or revoked
`WRITE_BLOCKED`	Write operation blocked by RBAC (editor/member role)
`ROLE_ESCALATION_DENIED`	Cannot create API Key with role higher than caller
`NOT_FOUND`	Resource not found or does not belong to tenant
`VALIDATION_ERROR`	Invalid data (schema_data, parameters)
`MODEL_TIER_RESTRICTED`	Model tier not allowed for the tenant's plan

Requirements

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

Source Code

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

Overview​

Setup​

Claude Desktop​

Claude Code​

Cursor​

Windsurf​

Codex (OpenAI)​

Other MCP Clients​

Environment Variables​

HTTP Transport​

Authentication​

Role-Based Access Control (RBAC)​

Tools Reference​

Consumer (4 tools)​

Agents (7 tools)​

Schemas (5 tools)​

Triggers (9 tools)​

Connections (6 tools)​

Connection Schema (3 tools)​

MCP Servers (7 tools)​

API Keys (5 tools)​

Security Policies — CSP (7 tools)​

Secrets (4 tools)​

Introspection and Validation (7 tools)​

Versioning (8 tools)​

Resources​

Guided Prompts​

Usage Examples​

Create an Agent with Guided Prompt​

Add a Database Tool​

Validate Before Publishing​

Limits and Configuration​

Error Handling​

Requirements​

Source Code​