Skip to main content
Glama
README.md
# Zihin MCP server

Connect MCP clients to the [Zihin.ai](https://zihin.ai) agent platform. This package
proxies stdio requests to the hosted MCP endpoint and includes platform skills.
Requires Node.js 20 or later and a Zihin API key.

## Quick start

```sh
ZIHIN_API_KEY=YOUR_ZIHIN_API_KEY npx -y @zihin/mcp-server
```

Obtain your key from the Zihin console. Store it in your client's secret configuration.
Use a key with the permissions needed for your work. Never commit it to a repository.

## Client configuration

Add this entry to your MCP client's configuration:

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

Clients with Streamable HTTP support can connect directly to
`https://llm.zihin.ai/mcp`, using the `X-Api-Key` header.
Available tools and resources depend on your account and key permissions.

## Claude Code plugin

```text
/plugin marketplace add zihin-ai/zihin-mcp
/plugin install zihin@zihin
```

Enter your key in the plugin's required, sensitive **Zihin API key** option. The plugin connects
directly to `https://llm.zihin.ai/mcp` over HTTP with the `X-Api-Key` header; it does
not start the npm proxy. Plugin versions advance independently of this package.
See [the plugin guide](plugin/README.md) for updates and configuration.

## Cursor plugin

The Cursor plugin connects directly to the hosted MCP endpoint and includes the same
platform skills. Configure the required `ZIHIN_API_KEY` variable under **Plugins → Configure**.
The repository contains only the variable declaration; never commit the key or put it
in a prompt. The API key determines which operations are available. Agent execution
can consume credits and perform external actions.

## Install skills

```sh
npx -y @zihin/mcp-server install-skills --client all --bundled
```

Supported clients are `claude`, `cursor`, `windsurf` and `codex`. Use `--dir` to choose
the project directory, or `--global` for Claude's user-level skills. Without `--bundled`,
the installer fetches skills from the server using your API key and falls back to bundled
skills if the server cannot supply them. Existing skill identifiers are retained for compatibility.

## Configuration

| Variable | Purpose |
| --- | --- |
| `ZIHIN_API_KEY` | Required API key |
| `ZIHIN_MCP_URL` | Optional trusted MCP endpoint; defaults to `https://llm.zihin.ai/mcp` |
| `ZIHIN_MCP_CALL_TIMEOUT_MS` | Tool-call timeout in milliseconds; default 300000, range 1000–1800000 |

The proxy sends your key to the configured endpoint. Change the endpoint only for a
trusted deployment. Diagnostics go to stderr; stdout carries MCP messages.
Agent execution can consume credits and trigger external actions. Inspect returned
errors and warnings before treating an operation as complete.

## Development

```sh
npm ci
npm test
npm run check:publication
```

Tests run offline without `ZIHIN_API_KEY`. Live integration tests require a test account
and key and can execute agents. `REQUIRE_INTEGRATION=1` makes a missing key an error.
The publication check rejects unexpected package files and known language regressions;
release review must also check all public text and exact artifact contents.

[Documentation](https://docs.zihin.ai/integrations/mcp-server) ·
[Security policy](SECURITY.md) · [License](LICENSE)

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