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/mcpTransport: Streamable HTTPAuth: Bearer token (your Shinzo API key)

Prerequisites

Before connecting, you’ll need:

A Shinzo account — sign up at app.shinzo.ai
A Shinzo API key — generate one from Settings → 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:

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

{
  "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):

{
  "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.

npm install @modelcontextprotocol/sdk

pip install mcp

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: {} });

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

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)

// 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 }
});

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

Connection refused or 401 Unauthorized

Verify your API key is correct and active — check Settings → 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)

Tools not showing up in Claude Code

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

mcp-remote errors in Claude Desktop

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

Shinzo Agents Docs

Learn about deploying and managing AI agents

API Reference

Explore the full Shinzo REST API

Agent Analytics

Monitor your agents with analytics

Support

Get help from the Shinzo team

​Shinzo MCP Server

​Prerequisites

​Connect Your MCP Client

​Claude Code (Recommended)

​Claude Desktop

​Generic MCP Client Configuration

​Custom Agents (TypeScript / Python)

​Available Tools

​Analytics (4 tools)

​Agent Management (11 tools)

​Agent Messaging (3 tools)

​Agent Filesystem (17 tools)

​File Operations (5 tools)

​Directory Operations (2 tools)

​Bulk Operations (3 tools)

​Metadata (2 tools)

​Archives (2 tools)

​Agent Schedules & Triggers (11 tools)

​Cron Schedules (7 tools)

​Webhook Triggers (4 tools)

​Discord Integration (3 tools)

​Slack Integration (3 tools)

​Telegram Integration (3 tools)

​MCP Server Management (13 tools)

​Server CRUD (5 tools)

​Server Operations (2 tools)

​Access Management (3 tools)

​Example: Create Your First Agent

​Via Claude Code (conversational)

​Via the TypeScript SDK (programmatic)

​Troubleshooting

​Next Steps

Shinzo Agents Docs

API Reference

Agent Analytics

Support

Shinzo MCP Server

Prerequisites

Connect Your MCP Client

Claude Code (Recommended)

Claude Desktop

Generic MCP Client Configuration

Custom Agents (TypeScript / Python)

Available Tools

Analytics (4 tools)

Agent Management (11 tools)

Agent Messaging (3 tools)

Agent Filesystem (17 tools)

File Operations (5 tools)

Directory Operations (2 tools)

Bulk Operations (3 tools)

Metadata (2 tools)

Archives (2 tools)

Agent Schedules & Triggers (11 tools)

Cron Schedules (7 tools)

Webhook Triggers (4 tools)

Discord Integration (3 tools)

Slack Integration (3 tools)

Telegram Integration (3 tools)

MCP Server Management (13 tools)

Server CRUD (5 tools)

Server Operations (2 tools)

Access Management (3 tools)

Example: Create Your First Agent

Via Claude Code (conversational)

Via the TypeScript SDK (programmatic)

Troubleshooting

Next Steps