yokigo-mcp-server

MCP server for Yokigo — AI workspace intelligence. Gives Claude Code, Codex, and other MCP clients access to 36 tools for calls, tasks, chats, documents, people, and knowledge graph.

Prerequisites

• Node.js 18+
• Yokigo API key (get one from Workspace Settings → API Keys in the app)

Credentials

You need two environment variables:

| Variable | Where to find | |---|---| | YOKIGO_API_BASE_URL | Take your Convex deployment URL and replace .convex.cloud with .convex.site. Example: https://festive-grouse-843.eu-west-1.convex.site | | YOKIGO_API_KEY | Workspace Settings → API Keys in the Yokigo app |

Setup — Claude Code

Option A: Project config file (recommended)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "yokigo": {
      "command": "npx",
      "args": ["-y", "yokigo-mcp-server"],
      "env": {
        "YOKIGO_API_BASE_URL": "<your-convex-site-url>",
        "YOKIGO_API_KEY": "<your-api-key>"
      }
    }
  }
}

Note: This file contains your API key — add .mcp.json to .gitignore if the repo is shared.

Option B: CLI command

If you have the claude CLI in your PATH:

claude mcp add-json yokigo '{"type":"stdio","command":"npx","args":["-y","yokigo-mcp-server"],"env":{"YOKIGO_API_BASE_URL":"<your-convex-site-url>","YOKIGO_API_KEY":"<your-api-key>"}}' --scope local

If claude command is not found, use Option A instead.

Setup — Codex

Append to ~/.codex/config.toml:

[[mcp_servers]]
name = "yokigo"
command = "npx"
args = ["-y", "yokigo-mcp-server"]

[mcp_servers.env]
YOKIGO_API_BASE_URL = "<your-convex-site-url>"
YOKIGO_API_KEY = "<your-api-key>"

Verify

1. Restart Claude Code after adding the config
2. Run /mcp — yokigo should show as connected
3. Send: Use Yokigo MCP. Call get_workspace_overview and show me the result.

Self-test

Test the connection without Claude Code:

YOKIGO_API_BASE_URL=https://... YOKIGO_API_KEY=yk_... npx yokigo-mcp-server --test

Expected output:

yokigo-mcp-server v0.3.0 — connection test

✓ Environment variables set
✓ Workspace: 5 calls, 12 topics, 3 tasks
All checks passed. Server is ready to use.

Troubleshooting

| Problem | Solution | |---|---| | claude command not found | Use Option A (.mcp.json file) instead of CLI | | Server not connecting after restart | Check that .mcp.json is in the project root, not inside .claude/. Both locations work, but the root is more reliable. | | "Missing YOKIGO_API_BASE_URL or YOKIGO_API_KEY" | Environment variables not set — check your config file for typos | | 401 Unauthorized | API key is invalid or expired — generate a new one in Workspace Settings | | Connection refused / network error | Base URL must end with .convex.site (not .convex.cloud) | | Tools not appearing | Run /mcp to check status. If yokigo shows an error, run the self-test above to diagnose. |

Usage

After connecting, the recommended first message:

Use Yokigo MCP. Start with get_workspace_overview and tell me what data already exists in this workspace.

Three main use cases:

1. Explore — get_workspace_overview, then list/read tools
2. Ingest — upload_call_transcript / upload_drive_file, then run_backend_extraction
3. Graph extraction — invoke the yokigo-graph-workflow prompt for the full 8-step workflow

License

MIT