Skip to main content

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:
  1. A Shinzo accountsign up at app.shinzo.ai
  2. 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. 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:
FieldValue
URLhttps://api.app.shinzo.ai/v1/mcp
TransportHTTP (Streamable HTTP)
AuthorizationBearer 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
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: {} });

Available Tools

Once connected, you’ll have access to tools across 6 categories:
CategoryToolsWhat you can do
Agent Management7 toolsCreate, configure, pause, and delete agents
Agent Messaging2 toolsSend messages and retrieve message history
Agent Filesystem5 toolsRead, write, and search files in agent workspaces
MCP Server Management5 toolsRegister servers and manage agent access
Token Analytics3 toolsQuery usage, costs, and session history
Discord Integration3 toolsLink/unlink Discord accounts to agents

Agent Management

ToolDescription
create_agentDeploy a new AI agent with custom configuration
list_agentsList all your agents with filtering and pagination
get_agentGet detailed info about a specific agent
update_agentUpdate an agent’s configuration, system prompt, or files
delete_agentDelete an agent and all its data
pause_agentTemporarily pause an agent
resume_agentResume a paused agent

Agent Messaging

ToolDescription
send_agent_messageSend a message to an agent via API, Discord, or other channels
list_agent_messagesRetrieve message history for an agent

Agent Filesystem

ToolDescription
read_agent_fileRead a file from an agent’s workspace
create_agent_fileCreate a new file in an agent’s workspace
update_agent_fileUpdate a file in an agent’s workspace
list_agent_directoryList files and folders in an agent’s workspace
search_agent_filesystemSearch files or content in an agent’s workspace

MCP Server Management

ToolDescription
create_mcp_serverRegister a new MCP server
list_mcp_serversList all registered MCP servers
grant_agent_mcp_accessGrant an agent access to an MCP server
revoke_agent_mcp_accessRevoke an agent’s MCP server access
check_mcp_server_healthCheck if an MCP server is reachable

Token Analytics

ToolDescription
get_token_analyticsGet AI token usage analytics and cost trends
list_ai_sessionsList AI interaction sessions with filtering
get_session_detailsGet detailed info about a specific session

Discord Integration

ToolDescription
create_discord_link_codeGenerate a code to link a Discord account to an agent
get_discord_statusCheck Discord link status for an agent
unlink_discordUnlink 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:
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.",
    channel: "api",
    queue_mode: "collect"
  }
});

// Retrieve the response
const messages = await client.callTool({
  name: "list_agent_messages",
  arguments: { agentId, limit: 10 }
});

Troubleshooting

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