> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Protocol
> Connect to OrgX from any MCP-compatible client.
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](https://modelcontextprotocol.io/) 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](/docs/api/mcp-tools) for hosted tools and [OpenClaw Plugin Tools](/docs/api/openclaw-plugin-mcp-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**:
1. Your MCP client discovers the auth server via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) metadata at `/.well-known/oauth-protected-resource`
2. You're redirected to sign in at [useorgx.com](https://useorgx.com) via Clerk
3. After approving the connection, the client receives and manages tokens automatically
4. Token refresh is handled transparently by the client
The fastest path is the [OpenClaw plugin](/docs/guides/openclaw-plugin-setup) —
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
The fastest setup — handles auth automatically:
```bash theme={"dark"}
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 →](/docs/guides/openclaw-plugin-setup)
Add to `~/.cursor/mcp.json`:
```json theme={"dark"}
{
"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:
```text theme={"dark"}
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:
```json theme={"dark"}
{
"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](/docs/guides/chatgpt-integration) |
| 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](/docs/api/mcp-tools) 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
* 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.
* 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.
* 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
Complete documentation for all tools.
Local bridge tools and scoped domain matrix.
Client-by-client setup for ChatGPT, Cursor, Claude, VS Code, and more.