MCP Protocol - OrgX Docs

OrgX exposes a Model Context Protocol (MCP) server that gives AI clients like ChatGPT, Claude, Cursor, and VS Code shared organizational memory for decisions, artifacts, approvals, delegated work, and project execution state.

Questions This Page Answers

Which endpoint should I use for hosted OrgX MCP vs local OpenClaw bridge?
How does OAuth work in practice for MCP clients?
What scopes should I request for decisions, dispatch, and memory workflows?
How do I avoid confusing the hosted OrgX tool surface with plugin-local tools?

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data. It enables:

Tools: Actions the AI can take (approve decisions, spawn tasks)
Resources: Data the AI can access (initiatives, artifacts)
Prompts: Pre-built conversation templates

Connecting to OrgX

Hosted MCP vs OpenClaw Local Bridge

OrgX supports two MCP connection modes:

Mode	Endpoint	Auth	Best for
Hosted OrgX MCP	`https://mcp.useorgx.com/mcp`	OAuth 2.1	ChatGPT, Claude, Cursor, VS Code, and other remote MCP clients
OpenClaw local bridge	`http://127.0.0.1:18789/orgx/mcp`	OpenClaw plugin pairing/API key	Local OpenClaw runtime + local dashboard

The hosted server and plugin bridge expose overlapping tools, but they are not identical surfaces.
Use the OrgX MCP Tools Reference for hosted tools and OpenClaw Plugin Tools for local bridge tools.

Server Endpoints

Endpoint	Protocol	Use Case
`https://mcp.useorgx.com/mcp`	Streamable HTTP	Recommended remote MCP endpoint
`https://mcp.useorgx.com/sse`	Server-Sent Events	Legacy SSE endpoint

Use https://mcp.useorgx.com/mcp for new clients. Use the SSE endpoint only when a legacy client cannot speak streamable HTTP.

Authentication

OrgX MCP uses OAuth 2.1 with browser-based authorization. Remote MCP clients that support OAuth handle sign-in automatically. How it works:

Your MCP client discovers the auth server via RFC 9728 metadata at /.well-known/oauth-protected-resource
You’re redirected to sign in at useorgx.com via Clerk
After approving the connection, the client receives and manages tokens automatically
Token refresh is handled transparently by the client

The fastest path is the OpenClaw plugin — 60-second browser pairing with no config files to edit.

Supported OAuth grant types: authorization_code, refresh_token PKCE support: S256, plain

Available Scopes

Request the scopes you need when authenticating:

Scope	What It Allows
`decisions:read`	View pending and past decisions
`decisions:write`	Approve or reject decisions
`agents:read`	View agent status and activity
`agents:write`	Spawn new agent tasks
`initiatives:read`	View initiatives and workstreams
`memory:read`	Search organizational knowledge

Quick Setup

OpenClaw (Recommended)
Cursor
Claude
VS Code

The fastest setup — handles auth automatically:

openclaw plugins install @useorgx/openclaw-plugin

Then open http://127.0.0.1:18789/orgx/live, click Connect OrgX, and approve in your browser.Full OpenClaw guide →

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "orgx": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.useorgx.com/mcp"
      ]
    }
  }
}

Restart Cursor. mcp-remote handles OAuth automatically — you’ll be prompted to sign in via your browser on first connect.

In Claude or Claude Desktop, open Settings → Connectors and add a custom remote MCP connector using:

https://mcp.useorgx.com/mcp

Complete OAuth in your browser when prompted. Anthropic’s current remote connector flow does not recommend configuring hosted remote MCP servers directly in claude_desktop_config.json.

Use MCP: Open User Configuration in VS Code, then add:

{
  "servers": {
    "orgx": {
      "type": "http",
      "url": "https://mcp.useorgx.com/mcp"
    }
  }
}

VS Code will handle OAuth in-browser on first use.

Supported Client Patterns

Client	Recommended setup	Widgets	Notes
ChatGPT	Add remote MCP server in Apps & Connectors	Yes	Use the `/mcp` endpoint; see the dedicated ChatGPT integration guide
Cursor	`mcp-remote` + hosted `/mcp` URL	Yes	Best option for IDE-assisted delivery
Claude / Claude Desktop	Remote connector in Settings	Yes	Use connector UI, not `claude_desktop_config.json`, for hosted remote MCP
VS Code	HTTP MCP server in `mcp.json`	Yes	Good fit for planning + delivery loops
Generic remote MCP clients	Hosted `/mcp` URL	Usually text fallback	Use when the client supports OAuth remote MCP but not widgets

Protocol Capabilities

OrgX MCP tools are organized by user intent. Start with the Tier-0 tools for tool routing, then use the lower-level tools when you need exact control.

Tier-0 Entry Points

orgx_decide - Save a decision to organizational memory
orgx_search - Search decisions, artifacts, and project context
orgx_decide - Review pending approvals and approve/reject after confirmation
orgx_spawn - Assign work to a specialist AI agent
orgx_recommend - Get initiative health, blockers, milestones, owners, and activity

Execution

orgx_spawn - High-recall wrapper for assigning work to an agent
orgx_spawn - Assign work to a specialized agent (Engineering, Marketing, Product, etc.)
orgx_act - Trigger lifecycle actions on any entity (start, complete, block, etc.)
scaffold_initiative - Create a full initiative hierarchy in one call
batch_create_entities - Bulk-create tasks, milestones, or workstreams in a single operation

Decisions

orgx_decide - High-recall wrapper for pending approval review
orgx_search - Filter type=decision and status=pending to list decisions awaiting approval
orgx_decide - Approve a decision
orgx_decide - Reject with feedback

Memory & Context

orgx_decide - Record a decision so agents can recall it later
orgx_search - High-recall wrapper for organizational memory search
orgx_search - Search organizational knowledge and past decisions
orgx_recommend - High-recall wrapper for project status and blockers
orgx_recommend - Get initiative health status and execution signals
orgx_recommend - Retrieve a full org-level summary for grounding agent context

Planning

orgx_plan - Open an interactive planning session for an initiative or workstream
orgx_plan - Apply structured improvements to an existing plan
orgx_plan - Finalize and commit a plan, making it actionable

See the MCP Tools Reference for complete documentation.

Legacy aliases such as orgx_decide and get_decision_history still resolve for older clients. For new natural-language client routing, prefer the Tier-0 tools above first, then drop down to orgx_search, orgx_search, and the direct write tools when needed.

Resources

The MCP server also exposes resources for rich context:

Resource	Description
`orgx://initiative/{id}`	Initiative details in markdown

Troubleshooting

Connection refused

Verify the endpoint URL matches your mode (hosted vs local bridge).
Hosted: ensure network access to mcp.useorgx.com.
Local bridge: ensure OpenClaw gateway is running and http://127.0.0.1:18789/orgx/live is reachable.

Authentication failed

Hosted OAuth: reconnect from your MCP client and complete browser sign-in again. - OpenClaw bridge: reconnect in plugin onboarding or re-enter a fresh oxk_... key. - Confirm your OrgX account has access to the target workspace.

Tools not appearing

Restart your IDE after updating config
Check MCP config syntax (mcpServers entry and endpoint URL).
If using OpenClaw, verify bridge health at /orgx/api/health and onboarding status at /orgx/api/onboarding/status.

Next Steps

MCP Tools Reference

Complete documentation for all tools.

OpenClaw Plugin Tools

Local bridge tools and scoped domain matrix.

MCP Client Setup

Client-by-client setup for ChatGPT, Cursor, Claude, VS Code, and more.

​Questions This Page Answers

​What is MCP?

​Connecting to OrgX

​Hosted MCP vs OpenClaw Local Bridge

​Server Endpoints

​Authentication

​Available Scopes

​Quick Setup

​Supported Client Patterns

​Protocol Capabilities

​Tier-0 Entry Points

​Execution

​Decisions

​Memory & Context

​Planning

​Resources

​Troubleshooting

​Next Steps

MCP Tools Reference

OpenClaw Plugin Tools

MCP Client Setup

Questions This Page Answers

What is MCP?

Connecting to OrgX

Hosted MCP vs OpenClaw Local Bridge

Server Endpoints

Authentication

Available Scopes

Quick Setup

Supported Client Patterns

Protocol Capabilities

Tier-0 Entry Points

Execution

Decisions

Memory & Context

Planning

Resources

Troubleshooting

Next Steps