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: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./mcp inside Claude Code — you should see shinzo listed as an available server.
Claude Desktop
Claude Desktop usesmcp-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
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 |
mcpServers config block (Cursor / Windsurf format):
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.Available Tools
Once connected, you’ll have access to tools across 6 categories:| Category | Tools | What you can do |
|---|---|---|
| Agent Management | 7 tools | Create, configure, pause, and delete agents |
| Agent Messaging | 2 tools | Send messages and retrieve message history |
| Agent Filesystem | 5 tools | Read, write, and search files in agent workspaces |
| MCP Server Management | 5 tools | Register servers and manage agent access |
| Token Analytics | 3 tools | Query usage, costs, and session history |
| Discord Integration | 3 tools | Link/unlink Discord accounts to agents |
Agent Management
| Tool | Description |
|---|---|
create_agent | Deploy a new AI agent with custom configuration |
list_agents | List all your agents with filtering and pagination |
get_agent | Get detailed info about a specific agent |
update_agent | Update an agent’s configuration, system prompt, or files |
delete_agent | Delete an agent and all its data |
pause_agent | Temporarily pause an agent |
resume_agent | Resume a paused agent |
Agent Messaging
| Tool | Description |
|---|---|
send_agent_message | Send a message to an agent via API, Discord, or other channels |
list_agent_messages | Retrieve message history for an agent |
Agent Filesystem
| Tool | Description |
|---|---|
read_agent_file | Read a file from an agent’s workspace |
create_agent_file | Create a new file in an agent’s workspace |
update_agent_file | Update a file in an agent’s workspace |
list_agent_directory | List files and folders in an agent’s workspace |
search_agent_filesystem | Search files or content in an agent’s workspace |
MCP Server Management
| Tool | Description |
|---|---|
create_mcp_server | Register a new MCP server |
list_mcp_servers | List all registered MCP servers |
grant_agent_mcp_access | Grant an agent access to an MCP server |
revoke_agent_mcp_access | Revoke an agent’s MCP server access |
check_mcp_server_health | Check if an MCP server is reachable |
Token Analytics
| Tool | Description |
|---|---|
get_token_analytics | Get AI token usage analytics and cost trends |
list_ai_sessions | List AI interaction sessions with filtering |
get_session_details | Get detailed info about a specific session |
Discord Integration
| Tool | Description |
|---|---|
create_discord_link_code | Generate a code to link a Discord account to an agent |
get_discord_status | Check Discord link status for an agent |
unlink_discord | Unlink a Discord account from an agent |
Example: Create Your First Agent
Via Claude Code (conversational)
Once connected, you can ask Claude to create and manage agents in plain English:Via the TypeScript SDK (programmatic)
Troubleshooting
Connection refused or 401 Unauthorized
Connection refused or 401 Unauthorized
Tools not showing up in Claude Code
Tools not showing up in Claude Code
- Run
claude mcp listto 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 shinzothen re-run the add command
mcp-remote errors in Claude Desktop
mcp-remote errors in Claude Desktop
- Ensure Node.js is installed:
node --version - Try running
npx mcp-remote --versionto 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

