Skip to main content

Connect to Koodisi MCP

Follow the instructions for your MCP client. Once connected, the client can sign in to Koodisi as you and build, publish, and deploy workflows on your behalf.

What you need​

  • A Koodisi account email and password.
  • An MCP client that supports a remote HTTP server with custom headers—for example Claude Code, Claude Desktop, Cursor, or Windsurf.

Note: Koodisi MCP authenticates with your account email and password sent as request headers—there's no separate client registration, client_id, or OAuth step.

Add the server​

Add this to your client's MCP configuration:

{
  "mcpServers": {
    "koodisi-mcp-server": {
      "url": "https://mcp.koodisi.com",
      "headers": {
        "email": "<YOUR_KOODISI_EMAIL>",
        "password": "<YOUR_KOODISI_PASSWORD>"
      }
    }
  }
}

Where that block goes depends on your client:

  • Claude Code — run claude mcp add-json koodisi-mcp-server '<the JSON above>', or add it under mcpServers in your project's .mcp.json.
  • Claude Desktop — Settings > Developer > Edit Config, then add it under mcpServers in claude_desktop_config.json.
  • Cursor — Cursor Settings > MCP > Add new global MCP server, then paste it into mcp.json.
  • Windsurf — open Windsurf Settings, search for MCP, select View raw config, and add it to mcp_config.json.

Restart or reload the client after saving.

Warning: Your password is stored in plain text in whatever config file you paste it into. Use a config file your client keeps local to your machine, and don't commit it to a shared repository.

Sign in​

Most MCP clients call tools only when you ask, so the first thing to do in a new conversation is ask your client to sign in:

  1. Ask your client to call sign_in. It reads your email and password from the email / password headers you set above, so you don't need to type them again.
  2. A successful sign-in returns your email back to confirm it worked.

Note: If sign_in returns an error, double-check the email and password in your client's config, then reload the client.

Select where you're working​

Koodisi MCP acts inside a specific organization, workspace, and app—select them once per session:

  1. Call list_orgs, then select_org with the organization you want.
  2. Call list_workspaces, then select_workspace with the workspace you want.
  3. Call list_apps to see existing apps, or create_app to make a new one, then select_app.
  4. Call get_context at any point to see what's currently selected.

Next: build something. See Supported tools for the full tool list, starting with compile_workflow_spec.

Troubleshooting​

ProblemCauseSolution
sign_in returns an errorWrong email/password, or the headers weren't sentRe-check the headers block in your client's config and reload the client.
A tool returns "No organization selected"You called an app-scoped tool before select_orgCall list_orgs → select_org → list_workspaces → select_workspace → select_app first.
A tool returns "No workspace selected" or "No app selected"You skipped select_workspace or select_appCall get_context to see what's missing, then select it.
Nothing happens when you ask the client to use a toolThe server isn't connectedConfirm the client shows koodisi-mcp-server as connected, then restart the client.
A tool returns "Unknown tool"The client's tool list is out of date, or the tool isn't on the server you're connected to yetReconnect the server in your client so it reloads the tool list.
create_app fails with HTTP 406, "active application limit reached"The workspace already has its maximum number of active apps (10)Deactivate an app you don't need with set_app_active (reversible), then try again.
A tool fails with "A valid bearer token is required" after a whileThe session's sign-in has expiredCall sign_in again, then select the organization, workspace and app again.