MCP client setup

Connect Claude, Cursor, Windsurf, and other MCP clients to the Orkestia workflow MCP server. The public endpoint is Streamable HTTP. Clients must POST — GET https://mcp.orkestia.dev/mcp returns 405 Method Not Allowed (Allow: DELETE, POST). That is correct.

Verified live (2026-09-04):

POST https://mcp.orkestia.dev/mcp without a token → 401 and WWW-Authenticate: Bearer resource_metadata="https://mcp.orkestia.dev/.well-known/oauth-protected-resource/mcp"
GET https://mcp.orkestia.dev/.well-known/oauth-authorization-server → issuer https://mcp.orkestia.dev, PKCE S256, grants authorization_code + refresh_token
Protected-resource metadata resource is exactly https://mcp.orkestia.dev/mcp

Endpoints

Endpoint	Use for	Auth
`https://mcp.orkestia.dev/mcp`	Human-operated external clients	OAuth 2.1 PKCE + DCR, or bearer header where the client cannot run browser OAuth
`http://ltinteg-workflow-mcp.ltinteg-product:8000/mcp`	In-cluster agents and platform runners	Scoped per-agent bearer header

Keep admin/project catalog tools disabled on shared public surfaces. Expose admin tools only through an admin-only deployment or a controlled operator path.

Cursor / generic client config

Put this in .cursor/mcp.json or ~/.cursor/mcp.json. Use OAuth for interactive sessions, or a token from Settings → API tokens for unattended work.

json

{
  "mcpServers": {
    "orkestia": {
      "type": "http",
      "url": "https://mcp.orkestia.dev/mcp"
    }
  }
}

Bearer fallback (no browser OAuth):

json

{
  "mcpServers": {
    "orkestia": {
      "type": "http",
      "url": "https://mcp.orkestia.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ORKESTIA_TOKEN}"
      }
    }
  }
}

The first tool call must be whoami. Do not pass organization_uuid — the server resolves it from the token.

Per-client pages: Cursor · Claude · Windsurf

Production prerequisites

The public server should run with:

bash

MCP_TRANSPORT=streamable-http
MCP_PUBLIC_URL=https://mcp.orkestia.dev
OAUTH_HOSTED_UI_ENABLED=true
OAUTH_ALLOW_LOOPBACK_REDIRECT=true
REDIS_URL=redis://...

Also configure COGNITO_HOSTED_DOMAIN, COGNITO_HOSTED_CLIENT_ID, and exact hosted callback URLs in OAUTH_REDIRECT_URI_ALLOWLIST.

Cursor desktop uses http://localhost:8787/callback. Cursor web / Agents uses https://www.cursor.com/agents/mcp/oauth/callback. Both must be allowlisted if those surfaces authenticate.

High-confidence clients

Client	Setup page	Recommended mode
Claude Code, Claude web/Desktop, Claude API	Claude	OAuth for interactive clients, bearer token for API callers
Cursor	Cursor	Remote Streamable HTTP + OAuth
Windsurf / Devin Desktop	Windsurf / Devin Desktop	Remote Streamable HTTP + OAuth
opencode	opencode	Remote MCP + OAuth, header fallback
Hermes	Hermes	OAuth PKCE/DCR/refresh, header fallback
Warp Cloud Agents	Warp	Bearer header only
OpenAI Responses / Agents	OpenAI Responses / Agents	Remote MCP URL + authorization token
Internal agent-runner	Internal agent-runner	In-cluster Streamable HTTP + bearer header
Python, LangGraph, LangChain	Python agents	MCP SDK Streamable HTTP + bearer header

Slack is handled through a Slack bridge, not as a direct MCP client today.

Common smoke test

Run this sequence for every client before calling it production-ready:

Connect to https://mcp.orkestia.dev/mcp (POST / Streamable HTTP).
Complete OAuth or send Authorization: Bearer AGENT_TOKEN.
Call whoami and confirm the expected organization.
Call list_workflow_types.
Call get_workflow_schema for one known workflow.
Start a harmless or dry-run workflow where available.
Call get_workflow_status and watch_workflow.
Confirm token refresh or token rotation behavior.
Confirm destructive tools require approval in user-facing clients.
Confirm audit logs show the right user, client, or agent.

MCP client setup ​

Endpoints ​

Cursor / generic client config ​

Production prerequisites ​

High-confidence clients ​

Common smoke test ​