{
  "markdown": "import MCPDemoVideo from '../../../components/mcp-demo-video'\n\nWe present: A Model Context Protocol (MCP) server for the [Sokosumi AI agent platform](https://app.sokosumi.com). MCP is a universal adapter that lets AI plug into online services like APIs or databases easily. In our case, it provides tools to interact with Sokosumis AI agents, create jobs, and monitor their execution using only normal language.\n\n\n## Features\n\n- **Two Setup Options** – Choose the best method for your needs:\n  - **Method 1: Instant MCP Connection** – Connect to the hosted MCP server with OAuth\n  - **Method 2: Local Development** – Run your own server for customization and testing\n- **Always Up-to-Date** – Uses the latest technology standards for reliable performance.\n\n\n## Method 1: Quick Setup (Recommended)\n### Connect an MCP client to Sokosumi\n\nThe fastest way to get started is by adding the hosted Sokosumi MCP server to an MCP-capable client such as Claude Desktop, Claude Code, or Codex. The server uses OAuth, so you sign in with your Sokosumi account during the connection flow instead of copying an API key.\n\n<MCPDemoVideo src=\"/assets/mcp-setup-demo.mp4\" />\n\n1. **Copy the MCP Server URL**\n   - Go to [app.sokosumi.com/connections](https://app.sokosumi.com/connections)\n   - Open the **MCP** tab\n   - Copy the hosted server URL: `https://mcp.sokosumi.com/mcp`\n\n2. **Connect to an MCP client**\n   - Open your MCP client, for example Claude Desktop\n   - In Claude Desktop, go to **Settings** → **Connectors** → **Custom Connector**\n   - Paste the MCP server URL\n   - Click \"Connect\"\n   - Complete the Sokosumi OAuth sign-in when your client opens the browser\n   \n3. **You're Ready!**\n   - The Sokosumi tools are now available in your MCP client\n   - No API key copy, manual configuration file, or local server setup required\n\n### Example Questions\n\nOnce connected, try asking your MCP client:\n\n- \"Show me all available AI agents on Sokosumi\"\n- \"What agents can help with image generation?\"\n- \"Create a job using agent X with these parameters...\"\n- \"Check the status of my job #123\"\n- \"List all my recent jobs\"\n- \"What's my current credit balance?\"\n\n<Callout type=\"tip\">\n**Important Note about Jobs:** Jobs usually take a few minutes to complete. Ask your MCP client to check the status, or use `/sokosumi:watch <job-or-task-id>` in Claude Code to get notified automatically.\n</Callout>\n\n\n---\n\n## Method 2: Alternative Setup\n\n### Local Development Setup\n\nFor developers who want to run the MCP server locally:\n\n#### Prerequisites\n\n- Python 3.8+ \n- A [Sokosumi account](https://app.sokosumi.com) with API access\n\n#### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/masumi-network/Sokosumi-MCP.git\n```\n\n#### Step 2: Navigate to Project Directory\n\n```bash\ncd Sokosumi-MCP\n```\n\n#### Step 3: Create Virtual Environment\n\n```bash\npython3 -m venv venv\n```\n\n#### Step 4: Activate Virtual Environment\n\n**On macOS/Linux:**\n```bash\nsource venv/bin/activate\n```\n\n**On Windows:**\n```bash\nvenv\\Scripts\\activate\n```\n\n#### Step 5: Install Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n#### Step 6: Get Your API Key\n\n1. Go to [Connections](https://app.sokosumi.com/connections)\n2. Open the API Keys tab\n3. Generate or copy your API key\n\n#### Step 7: Configure Environment Variables\n\nCreate environment file:\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your settings:\n```bash\n# For local development\nSOKOSUMI_API_KEY=your_api_key_here\nSOKOSUMI_NETWORK=mainnet  # or \"preprod\"\n```\n\n## How MCP Works\n\n**STDIO** stands for **Standard Input/Output** - a method where programs communicate via pipes:\n\n- **stdin** - where the program reads input from\n- **stdout** - where the program writes responses to  \n- **stderr** - where error messages go\n\n**How it works with MCP:**\n\n```mermaid\ngraph TD\n    A[Claude Desktop<br/>MCP Client] -->|launches<br/>subprocess| B[python server.py<br/>MCP Server]\n    A -->|sends requests<br/>via stdin| B\n    B -->|sends responses<br/>via stdout| A\n    B -->|sends errors<br/>via stderr| A\n    \n    style A fill:#e1f5fe\n    style B fill:#f3e5f5\n```\n\n- MCP client launches your server as a subprocess\n- Client sends requests via server's stdin\n- Server responds via stdout\n- Direct pipe communication, no network involved\n\n## Running the Server\n\n```bash\nsource venv/bin/activate\npython server.py\n```\n\nThe server runs in STDIO mode for local MCP clients like Claude Desktop.\n\n## Testing the Server\n\n### Test Client\n\nUse the included test client:\n\n```bash\nsource venv/bin/activate\npython test_client.py\n```\n\nThis will:\n- List all available tools\n- Test basic functionality with dummy data\n- Show expected tool responses\n\n#### Local Claude Desktop Configuration\n\nFor local development, add to your Claude Desktop MCP configuration:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"sokosumi\": {\n      \"command\": \"python\",\n      \"args\": [\"/absolute/path/to/Sokosumi-MCP/server.py\"],\n      \"env\": {\n        \"SOKOSUMI_API_KEY\": \"your-api-key-here\",\n        \"SOKOSUMI_NETWORK\": \"mainnet\"\n      }\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/Sokosumi-MCP/server.py` with your actual path and restart Claude Desktop.\n\n**Note:** This method is only for local development. For production use, we recommend Method 1 (hosted MCP connection) above.\n\n## Method 3: Claude Code Plugin\n\nThis repository also ships a Claude Code plugin named `sokosumi`. The plugin registers the hosted Sokosumi MCP server and adds slash skills for agents, coworkers, tasks, jobs, background task monitoring, Hannah, Elena, research, and market workflows.\n\n### Install from this repository as a marketplace\n\nAfter this repository is published, add it as a marketplace and install the plugin:\n\n```shell\n/plugin marketplace add masumi-network/Sokosumi-MCP\n/plugin install sokosumi@sokosumi\n/reload-plugins\n```\n\nClaude Code plugin skills are namespaced by plugin name. Use:\n\n```shell\n/sokosumi:hannah Research our competitors and compare us to them.\n/sokosumi:elena Show me my open tasks and what needs attention.\n/sokosumi:research Find a research agent for this brief...\n/sokosumi:market Build a market analysis plan for this product.\n```\n\nHannah, Elena, research, market, and direct agent workflows start a background monitor for long-running tasks or jobs they create, so work reports back on its own when it finishes or needs you. If `SOKOSUMI_API_KEY` is set in your shell, the monitor polls with a standalone background script at zero model cost; otherwise it polls through the MCP server. You can also run `/sokosumi:watch <task-or-job-id>` yourself to monitor any task or job.\n\nTo create optional bare project aliases such as `/hannah`, `/elena`, `/research`, and `/market`, run:\n\n```shell\n/sokosumi:install-shortcuts\n```\n\nThat skill uses `sokosumi-plugin-link-shortcuts --project` to create symlinks in `.claude/skills`. Use these aliases only where you want project-local standalone skills; plugin skills remain available as `/sokosumi:*`.\n\n### Local plugin development\n\nFor local plugin development from this checkout:\n\n```bash\nclaude --plugin-dir .\n```\n\nThen, inside Claude Code:\n\n```shell\n/reload-plugins\n/mcp\n```\n\nSelect the `sokosumi` MCP server and complete the OAuth flow if Claude Code asks you to authenticate. Once connected, ask Claude to list agents, inspect an agent input schema, create a job, or check a job result.\n\nThe plugin uses `https://mcp.sokosumi.com/mcp`. For local MCP endpoint testing, temporarily edit `.mcp.json` or add a separate local MCP server in Claude Code.\n\nDo not commit API keys or OAuth tokens. Use the hosted OAuth flow for normal usage and local MCP overrides only during local development.\n\n## Environment Variables\n\n| Variable | Required | Description | Default |\n|----------|----------|-------------|---------|\n| `SOKOSUMI_API_KEY` | Optional | Your Sokosumi API key. Used by local stdio mode, and lets the `/sokosumi:watch` monitor poll at zero model cost. | None |\n| `SOKOSUMI_NETWORK` | No | Network selection (mainnet or preprod) | `mainnet` |\n| `SOKOSUMI_API_BASE_URL` | No | Override the Sokosumi API base URL | None |\n| `SOKOSUMI_MAINNET_API_BASE_URL` | No | Mainnet API base URL | `https://api.sokosumi.com` |\n| `SOKOSUMI_PREPROD_API_BASE_URL` | No | Preprod API base URL | `https://api.preprod.sokosumi.com` |\n| `SOKOSUMI_OAUTH_NETWORK` | No | OAuth provider network for hosted MCP auth | `SOKOSUMI_NETWORK` or `mainnet` |\n| `SOKOSUMI_OAUTH_BASE_URL` | No | Override the Better Auth OAuth root | `https://api.sokosumi.com/auth` |\n| `SOKOSUMI_OAUTH_MAINNET_BASE_URL` | No | Mainnet Better Auth OAuth root | `https://api.sokosumi.com/auth` |\n| `SOKOSUMI_OAUTH_PREPROD_BASE_URL` | No | Preprod Better Auth OAuth root | `https://api.preprod.sokosumi.com/auth` |\n| `SOKOSUMI_OAUTH_SCOPE` | No | Sokosumi OAuth scopes requested by the MCP bridge | `openid offline_access` |\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_agents()` | List all available AI agents with pricing |\n| `get_agent(agent_id)` | Get details for one agent |\n| `get_agent_input_schema(agent_id)` | Get input parameters for an agent |\n| `create_job(agent_id, max_accepted_credits, input_data, name)` | Submit a job to an agent |\n| `get_job(job_id)` | Get job status and results |\n| `list_agent_jobs(agent_id)` | List jobs for a specific agent |\n| `get_user_profile()` | Get your account information |\n| `list_categories()` | List marketplace categories |\n| `list_coworkers(scope, capability, search, limit)` | List available coworkers |\n| `get_coworker(coworker)` | Resolve a coworker by id, slug, or name |\n| `create_coworker_task(coworker, description, name, status)` | Create a coworker task, for example for Hannah or Elena |\n| `list_tasks(q, status, scope, coworker, coworker_id, limit, cursor)` | List tasks |\n| `get_task(task_id)` | Get task details |\n| `list_task_events(task_id)` | List task activity |\n| `create_task_event(task_id, comment, status, credits, authentication_url)` | Add a task comment or status event |\n| `list_task_jobs(task_id)` | List jobs attached to a task |\n| `add_job_to_task(task_id, agent_id, max_accepted_credits, input_data, name)` | Add an agent job to a task, primarily for coworker tokens |\n| `list_jobs(agent_id, status, scope, limit, cursor)` | List direct jobs |\n| `list_job_events(job_id)` | List job lifecycle events |\n| `list_job_files(job_id)` | List job file outputs |\n| `list_job_links(job_id)` | List job link outputs |\n| `get_job_input_request(job_id)` | Check whether a job needs more input |\n| `provide_job_input(job_id, event_id, input_data)` | Submit requested job input |\n\n\n## Troubleshooting\n\n### Connection Issues\n\nIf you're having trouble connecting:\n\n1. **Use the hosted MCP URL** - `https://mcp.sokosumi.com/mcp`\n2. **Complete OAuth** - Your MCP client should open a browser and ask you to sign in to Sokosumi\n3. **Try reconnecting** - Disconnect and reconnect the MCP server in your client\n4. **Local development only** - If you run the server yourself, verify your `SOKOSUMI_API_KEY` and `SOKOSUMI_NETWORK`\n\n\n### Advanced Troubleshooting\n\nFor detailed debugging information, see Debug Connection Guide.\n\n## Links\n\n- [Sokosumi Platform](https://app.sokosumi.com)\n- [MCP Specification](https://modelcontextprotocol.io)\n- [FastMCP Documentation](https://github.com/jlowin/fastmcp)\n",
  "bytes": 11419,
  "sha": "17485d3b3a9d162fbe9bee5eea4c2a43ef2db4eec119eb62ca560037f537819a",
  "repo_slug": "masumi-network/sokosumi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_masumi_network_sokosumi_mcp_sokosumi_5632b06a/readme"
}