> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Shinzo MCP Server
> Connect your MCP client to the Shinzo platform to deploy and manage AI agents
# Shinzo MCP Server
The Shinzo MCP server gives your AI assistants and agents direct access to the Shinzo platform. Once connected, you can deploy agents, manage MCP servers, send messages, and more — all from within Claude Code or any MCP-compatible client.
**Server URL**: `https://api.app.shinzo.ai/v1/mcp`
**Transport**: Streamable HTTP
**Auth**: Bearer token (your Shinzo API key)
## Prerequisites
Before connecting, you'll need:
1. A **Shinzo account** — [sign up at app.shinzo.ai](https://app.shinzo.ai)
2. A **Shinzo API key** — generate one from [Settings → API Keys](https://app.shinzo.ai/spotlight/api-keys) in the platform
Your API key starts with `sk-`. When configuring clients, the full Authorization header value should look like: `Bearer sk-abc123def456...` (include the word "Bearer" followed by a space and your key).
***
## Connect Your MCP Client
Choose the setup method that works best for your MCP client.
### Claude Code (Recommended)
The fastest way to add Shinzo to Claude Code is with a single CLI command:
```bash theme={null}
claude mcp add --transport http shinzo "https://api.app.shinzo.ai/v1/mcp" --header "Authorization: Bearer YOUR_SHINZO_API_KEY"
```
Replace `YOUR_SHINZO_API_KEY` with your actual API key.
**Important**: The `--transport` flag must come **before** the server name (`shinzo`) in the command. Placing it after will cause a parsing error.
After running this command, restart Claude Code. You can verify the connection with `/mcp` inside Claude Code — you should see `shinzo` listed as an available server.
You can also run `/mcp` inside a Claude Code session to verify all connected MCP servers and their tool counts.
***
### Claude Desktop
Claude Desktop uses `mcp-remote` as a bridge to HTTP MCP servers. Add the following to your Claude Desktop configuration file:
**Config file location:**
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"shinzo": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.app.shinzo.ai/v1/mcp",
"--header",
"Authorization: Bearer YOUR_SHINZO_API_KEY"
]
}
}
}
```
`mcp-remote` requires Node.js. It will be downloaded automatically via `npx` on first use. Restart Claude Desktop after updating the config file.
***
### Generic MCP Client Configuration
For any MCP client that supports HTTP transport (Streamable HTTP or SSE) — including Cursor, Windsurf, VS Code Copilot, and others — use these connection details:
| Field | Value |
| ----------------- | ---------------------------------- |
| **URL** | `https://api.app.shinzo.ai/v1/mcp` |
| **Transport** | HTTP (Streamable HTTP) |
| **Authorization** | `Bearer YOUR_SHINZO_API_KEY` |
**Example `mcpServers` config block (Cursor / Windsurf format):**
```json theme={null}
{
"mcpServers": {
"shinzo": {
"type": "http",
"url": "https://api.app.shinzo.ai/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_SHINZO_API_KEY"
}
}
}
}
```
Config field names vary by client. Cursor and Windsurf use `"type": "http"`. Other clients (e.g. VS Code Copilot extensions) may use `"transportType"` or similar. Consult your client's documentation if the above doesn't work — the URL and Authorization header values are always the same.
***
### Custom Agents (TypeScript / Python)
You can connect your own agents to the Shinzo MCP server using the official MCP SDKs.
```bash Install (TypeScript) theme={null}
npm install @modelcontextprotocol/sdk
```
```bash Install (Python) theme={null}
pip install mcp
```
```typescript TypeScript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const transport = new StreamableHTTPClientTransport(
new URL("https://api.app.shinzo.ai/v1/mcp"),
{
requestInit: {
headers: {
Authorization: "Bearer YOUR_SHINZO_API_KEY"
}
}
}
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
// List your agents
const agents = await client.callTool({ name: "list_agents", arguments: {} });
```
```python Python theme={null}
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client(
"https://api.app.shinzo.ai/v1/mcp",
headers={"Authorization": "Bearer YOUR_SHINZO_API_KEY"}
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
# List your agents
agents = await session.call_tool("list_agents", {})
```
***
## Available Tools
Once connected, you'll have access to **66 tools** across 9 categories:
| Category | Tools | What you can do |
| ------------------------------ | -------- | --------------------------------------------------------------- |
| **Analytics** | 4 tools | Query usage, costs, and session history |
| **Agent Management** | 11 tools | Create, configure, pause, and delete agents |
| **Agent Messaging** | 3 tools | Send messages and retrieve conversation history |
| **Agent Filesystem** | 17 tools | Read, write, search, and organize files in agent workspaces |
| **Agent Schedules & Triggers** | 11 tools | Create recurring cron schedules and webhook triggers for agents |
| **Discord Integration** | 3 tools | Link/unlink Discord accounts |
| **Slack Integration** | 3 tools | Link/unlink Slack accounts to agents |
| **Telegram Integration** | 3 tools | Link/unlink Telegram accounts to agents |
| **Channel Management** | 1 tool | Manage channel bindings for agents |
| **MCP Server Management** | 13 tools | Register servers, manage agent access, and check health |
***
### Analytics (4 tools)
Monitor token usage, costs, and session activity.
| Tool | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `get_usage_summary` | Get today/week/month token usage summary — fastest way to answer "how many tokens did I burn?" |
| `get_token_analytics` | Get detailed token usage analytics aggregated by model and provider |
| `list_ai_sessions` | List AI interaction sessions with filtering and pagination |
| `get_session_details` | Get detailed info about a specific session including interactions, request/response data, and linked messages |
**Usage examples:**
* "How many tokens did I use today?"
* "Show me the most expensive sessions this month"
* "Get details for session abc-123"
***
### Agent Management (11 tools)
Create, configure, and control your AI agents.
| Tool | Description |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `create_agent` | Deploy a new AI agent with custom configuration, system prompt, and initial files |
| `list_agents` | List all your agents with filtering, sorting, and pagination |
| `get_agent` | Get detailed info about a specific agent (system prompt, MCP servers, filesystem summary) |
| `get_agent_summary` | Get slim agent summary (status, token balance, message count) — faster than `get_agent` |
| `update_agent` | Update agent configuration, system prompt, files, or MCP server access |
| `delete_agent` | Delete an agent and all its data |
| `pause_agent` | Pause agent execution loop (pod stays alive for filesystem access) |
| `resume_agent` | Resume a paused or stopped agent |
| `stop_agent` | Stop agent and shut down pod (workspace preserved) |
| `set_agent_status` | Set agent status directly (active, paused, or stopped) |
| `update_agent_balance` | Update agent output token balance (increment or set) |
**Usage examples:**
* "Create a research agent with 2GB storage"
* "List all active agents"
* "Pause agent abc-123 while I update its config"
* "Add 100k tokens to agent abc-123's balance"
***
### Agent Messaging (3 tools)
Send messages to agents and retrieve conversation history.
| Tool | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------- |
| `send_agent_message` | Send a message to an agent via API channel (supports queue modes: collect or interrupt) |
| `list_agent_messages` | List messages for an agent with filtering (status, sender, recipient, counterparty) and cursor pagination |
| `list_agent_conversations` | List conversations grouped by counterparty with message counts and recent messages |
**Usage examples:**
* "Send 'analyze this dataset' to agent abc-123"
* "Show unread messages for agent abc-123"
* "List all conversations for agent abc-123"
***
### Agent Filesystem (17 tools)
Full programmatic access to agent workspace files and directories.
#### File Operations (5 tools)
| Tool | Description |
| ------------------- | -------------------------------------------------------- |
| `read_agent_file` | Read file contents (supports UTF-8 and base64 encoding) |
| `create_agent_file` | Create a new file with optional overwrite |
| `update_agent_file` | Update existing file contents |
| `delete_agent_file` | Delete a file |
| `patch_agent_file` | Apply partial updates (append, prepend, insert, replace) |
#### Directory Operations (2 tools)
| Tool | Description |
| ------------------------ | ------------------------------------------------------------- |
| `list_agent_directory` | List directory contents (supports recursive and hidden files) |
| `create_agent_directory` | Create directory (supports recursive parent creation) |
| `delete_agent_directory` | Delete directory (supports recursive deletion) |
#### Bulk Operations (3 tools)
| Tool | Description |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `copy_agent_path` | Copy file or directory with overwrite support |
| `move_agent_path` | Move or rename file/directory with overwrite support |
| `search_agent_filesystem` | Search by filename, content, or both (supports glob patterns, case sensitivity, max results) |
#### Metadata (2 tools)
| Tool | Description |
| ---------------------- | -------------------------------------------------------------- |
| `get_file_metadata` | Get file or directory metadata (size, permissions, timestamps) |
| `update_file_metadata` | Update file metadata (permissions, owner, group, tags) |
#### Archives (2 tools)
| Tool | Description |
| ----------------------- | ----------------------------------------------------- |
| `create_agent_archive` | Create archive from files (zip, tar, tar.gz, tar.bz2) |
| `extract_agent_archive` | Extract archive to destination path |
**Usage examples:**
* "Read the config.json file from agent abc-123"
* "Create a requirements.txt file in agent abc-123's workspace"
* "Search for 'TODO' in all Python files for agent abc-123"
* "Create a backup archive of agent abc-123's entire workspace"
***
### Agent Schedules & Triggers (11 tools)
Automate agent tasks with recurring cron schedules and event-driven webhook triggers.
#### Cron Schedules (7 tools)
| Tool | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_schedule` | Create a recurring cron schedule for an agent (supports timezone, cron expression, message template with `{{date}}`, `{{time}}`, `{{schedule.name}}` variables) |
| `list_schedules` | List all schedules for an agent with pagination |
| `get_schedule` | Get details of a specific schedule |
| `update_schedule` | Update schedule name, cron expression, message template, timezone, or enabled state |
| `toggle_schedule` | Toggle a schedule between enabled and disabled |
| `delete_schedule` | Delete a cron schedule |
| `list_schedule_executions` | List execution history for a schedule (last 50 runs by default) |
#### Webhook Triggers (4 tools)
| Tool | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_trigger` | Create a webhook trigger for an agent (returns webhook URL and auto-generated secret; message template supports `{{payload.*}}` dot-path substitution from JSON payload) |
| `list_triggers` | List all webhook triggers for an agent with pagination |
| `update_trigger` | Update trigger name, message template, or enabled state |
| `delete_trigger` | Delete a webhook trigger |
**Usage examples:**
* "Create a daily standup reminder at 9am PST for agent abc-123"
* "Set up a webhook trigger for agent abc-123 to process GitHub push events"
* "List all schedules for agent abc-123"
* "Show execution history for schedule xyz-789"
* "Disable the weekend backup schedule for agent abc-123"
**Cron Schedule Examples:**
* `0 9 * * 1-5` — Every weekday at 9:00 AM
* `0 */4 * * *` — Every 4 hours
* `0 0 * * 0` — Every Sunday at midnight
* `30 14 1 * *` — First day of every month at 2:30 PM
**Webhook Authentication:**
Webhooks support both `X-Webhook-Secret` (plain secret) and `X-Hub-Signature-256` (GitHub-style HMAC) headers for secure validation.
***
### Discord Integration (3 tools)
Connect agents to Discord for user interactions.
| Tool | Description |
| -------------------------- | -------------------------------------------------------------------------------- |
| `create_discord_link_code` | Generate a 6-character code to link Discord account to agent (expires in 10 min) |
| `get_discord_status` | Check Discord link status and binding details for an agent |
| `unlink_discord` | Unlink Discord account from agent (deactivates channel binding) |
**Usage examples:**
* "Generate Discord link code for agent abc-123"
* "Check Discord status for agent abc-123"
* "Unlink Discord from agent abc-123"
***
### Slack Integration (3 tools)
Connect agents to Slack for team communication.
| Tool | Description |
| ------------------------ | ------------------------------------------------------------------------------ |
| `create_slack_link_code` | Generate a 6-character code to link Slack account to agent (expires in 10 min) |
| `get_slack_status` | Check Slack link status and binding details for an agent |
| `unlink_slack` | Unlink Slack account from agent (deactivates channel binding) |
**Usage examples:**
* "Generate Slack link code for agent abc-123"
* "Check Slack status for agent abc-123"
* "Unlink Slack from agent abc-123"
**Note**: Slack integration requires either the centralized Shinzo Slack bot or a custom Slack bot configured for your agent. See the [Slack Integration Guide](/channels/slack) for setup instructions.
***
### Telegram Integration (3 tools)
Connect agents to Telegram for user interactions.
| Tool | Description |
| --------------------------- | --------------------------------------------------------------------------------- |
| `create_telegram_link_code` | Generate a 6-character code to link Telegram account to agent (expires in 10 min) |
| `get_telegram_status` | Check Telegram link status and binding details for an agent |
| `unlink_telegram` | Unlink Telegram account from agent (deactivates channel binding) |
**Usage examples:**
* "Generate Telegram link code for agent abc-123"
* "Check Telegram status for agent abc-123"
* "Unlink Telegram from agent abc-123"
***
### MCP Server Management (13 tools)
Register, configure, and manage MCP servers for your agents.
#### Server CRUD (5 tools)
| Tool | Description |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `create_mcp_server` | Register new MCP server (stdio or HTTP, with init steps, files, and environment variables) |
| `list_mcp_servers` | List all registered MCP servers with filtering and pagination |
| `get_mcp_server` | Get detailed info about MCP server including agent access grants |
| `update_mcp_server` | Update MCP server configuration, credentials, or status |
| `delete_mcp_server` | Delete MCP server (fails if agents have active access grants) |
#### Server Operations (2 tools)
| Tool | Description |
| -------------------------- | ------------------------------------------------------------ |
| `refresh_mcp_server_tools` | Refresh available tools list by querying MCP server endpoint |
| `check_mcp_server_health` | Check MCP server health and connectivity |
#### Access Management (3 tools)
| Tool | Description |
| ------------------------- | -------------------------------------------------------------- |
| `grant_agent_mcp_access` | Grant agent access to MCP server (all tools or selected tools) |
| `revoke_agent_mcp_access` | Revoke agent's MCP server access |
| `list_agent_mcp_access` | List all agent access grants for an MCP server |
**Usage examples:**
* "Register the GitHub MCP server for my agents"
* "Grant agent abc-123 access to the github server"
* "Check health of the filesystem server"
* "List all agents that can access the github server"
***
## Example: Create Your First Agent
### Via Claude Code (conversational)
Once connected, you can ask Claude to create and manage agents in plain English:
```
You: Create a new Shinzo agent called "research-assistant" with the description
"Helps with research tasks" and the system prompt "You are a helpful research
assistant. Always cite your sources."
Claude: I'll create that agent for you using the Shinzo MCP server.
[create_agent result]
{
"uuid": "abc123de-f456-7890-abcd-ef1234567890",
"name": "research-assistant",
"status": "active",
"created_at": "2026-02-18T10:30:00Z"
}
The agent "research-assistant" has been created and is now active. Its ID is
abc123de-f456-7890-abcd-ef1234567890. You can send it messages using
send_agent_message, or connect it to additional MCP servers using
grant_agent_mcp_access.
```
### Via the TypeScript SDK (programmatic)
```typescript TypeScript theme={null}
// Create an agent and send it a message
const newAgent = await client.callTool({
name: "create_agent",
arguments: {
name: "research-assistant",
description: "Helps with research tasks",
system_prompt: "You are a helpful research assistant. Always cite your sources.",
configuration: {}
}
});
// Extract agent UUID from tool response
const agentId = JSON.parse(newAgent.content[0].text).uuid;
// Send the agent its first message
await client.callTool({
name: "send_agent_message",
arguments: {
agentId,
content: "Summarize the latest developments in large language models.",
queue_mode: "collect"
}
});
// Retrieve the response
const messages = await client.callTool({
name: "list_agent_messages",
arguments: { agentId, limit: 10 }
});
```
```python Python theme={null}
import json
# Create an agent
result = await session.call_tool("create_agent", {
"name": "research-assistant",
"description": "Helps with research tasks",
"system_prompt": "You are a helpful research assistant. Always cite your sources.",
"configuration": {}
})
# Extract agent UUID from tool response
agent_id = json.loads(result.content[0].text)["uuid"]
# Send the agent its first message
await session.call_tool("send_agent_message", {
"agentId": agent_id,
"content": "Summarize the latest developments in large language models.",
"queue_mode": "collect"
})
# Retrieve the response
messages = await session.call_tool("list_agent_messages", {
"agentId": agent_id,
"limit": 10
})
```
***
## Troubleshooting
* Verify your API key is correct and active — check [Settings → API Keys](https://app.shinzo.ai/spotlight/api-keys)
* Make sure you're passing the full key (starts with `sk-...`), not just the key prefix
* Check that the `Authorization` header is formatted as `Bearer YOUR_KEY` (with a space between "Bearer" and the key)
* Run `claude mcp list` to verify the server was added
* Restart Claude Code after adding the server
* Check for errors with `claude mcp get shinzo`
* Try removing and re-adding: `claude mcp remove shinzo` then re-run the add command
* Ensure Node.js is installed: `node --version`
* Try running `npx mcp-remote --version` to test if mcp-remote works
* Check Claude Desktop logs for detailed error messages
* Make sure there are no JSON syntax errors in your config file
***
## Next Steps
Learn about deploying and managing AI agents
Explore the full Shinzo REST API
Monitor your agents with analytics
Get help from the Shinzo team