Orkestia Reference

Appearance

Proud to collaborate with Microsoft for Startups
Proud to collaborate with Microsoft for Startups

Claude MCP client setup ​

Claude is the first client family to smoke test because it exercises both hosted OAuth callbacks and native loopback OAuth.

Supported paths ​

SurfaceMode
Claude CodeRemote MCP URL + OAuth/DCR + loopback redirect
Claude web / DesktopRemote MCP URL + OAuth/DCR + hosted callback
Claude API / Managed AgentsRemote MCP URL + bearer token supplied by the calling app

Server settings ​

bash
MCP_PUBLIC_URL=https://mcp.orkestia.dev
OAUTH_ALLOW_LOOPBACK_REDIRECT=true
OAUTH_REDIRECT_URI_ALLOWLIST=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback

Keep REDIS_URL configured before using more than one MCP server replica.

Claude Code ​

Add the remote MCP server using Claude Code's remote MCP flow and point it to:

text
https://mcp.orkestia.dev/mcp

When Claude marks the server as requiring authentication, run Claude Code's MCP auth flow. The MCP server advertises:

text
/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server
/register
/authorize
/token

Expected result: Claude opens Cognito hosted UI or a local browser OAuth flow, then stores the resulting token and calls MCP tools with Authorization: Bearer ....

Claude web / Desktop ​

Add the remote MCP connector with:

text
https://mcp.orkestia.dev/mcp

The hosted callback must match one of the allowlisted Claude URLs exactly. If DCR is rejected, check OAUTH_REDIRECT_URI_ALLOWLIST first.

Claude API / Managed Agents ​

For API callers, the app supplies a token in the MCP server definition:

json
{
  "type": "url",
  "url": "https://mcp.orkestia.dev/mcp",
  "name": "orkestia-workflow",
  "authorization_token": "ORKESTIA_ACCESS_TOKEN"
}

Use a user token for user-scoped actions and a scoped agent token for unattended jobs.

Smoke test ​

Ask Claude to:

text
Call whoami, list workflow types, inspect one workflow schema, then watch a harmless workflow run to completion.

The first tool call should be whoami. If Claude can list tools but workflow calls fail with auth errors, inspect token validation in the MCP server logs and /api/auth/me fallback behavior.

Official docs ​