> ## 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.

# OrgX MCP

> Give every MCP-compatible assistant shared workspace context, accountable execution, and reviewable proof.

OrgX MCP gives every MCP-compatible assistant a shared, reviewable record of
organizational work. Connect once to carry decisions, owners, delegated work,
artifacts, approvals, and proof across clients and conversations.

Ask naturally. Your assistant chooses the right OrgX tool. Use this page when
you want to connect, understand the work model, or find the safest next call.
Use the [MCP Tools Reference](https://docs.useorgx.com/docs/api/mcp-tools.md) when you need the exact contract
for every tool.

## Connect

Add this remote MCP server to any compatible client:

```text theme={"dark"}
https://mcp.useorgx.com/mcp
```

The hosted endpoint uses OAuth 2.1 with PKCE. Your client opens OrgX in a
browser, where you sign in and choose the workspace and access you want to
grant. No API key is required.

> [!NOTE]
>
> Use the streamable HTTP endpoint above for new clients. The legacy SSE
> endpoint is available at [https://mcp.useorgx.com/sse](https://mcp.useorgx.com/sse) when a client cannot
> use streamable HTTP. ChatGPT users can connect OrgX from the ChatGPT plugin
> directory; a manual Developer Mode connector uses
> [https://mcp.useorgx.com/mcp?profile=chatgpt](https://mcp.useorgx.com/mcp?profile=chatgpt).

**1. Add the endpoint**

Paste the hosted URL into your MCP client or use the client-specific setup
below.

**2. Approve the connection**

Complete the browser sign-in and review the workspace plus requested
resource access before approving.

**3. Confirm the session**

Call `orgx_bootstrap`. Do not start work until the returned
workspace and visible tools match what you intended to authorize.

> [!TIP]
>
> A healthy connection has a valid OAuth session, the expected workspace, a
> non-empty `granted_scopes` value, and the tools required for the
> current workflow in `visible_tools`.

## Quick setup by client

> [tab] ChatGPT
>
> Open the
> [OrgX listing in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a1083cac4788191a47b657dc58c4315),
> choose **Connect**, and complete the OrgX OAuth flow. No Developer Mode is
> needed.
>
> If directory plugins are unavailable in your workspace, enable Developer
> Mode under **Settings → Security and login** and add a custom connector
> with:
>
> ```text theme={"dark"}
> https://mcp.useorgx.com/mcp?profile=chatgpt
> ```
>
> See the
> [ChatGPT integration guide](https://docs.useorgx.com/docs/guides/chatgpt-integration.md) for the
> ChatGPT-specific connection and widget checks.

> [tab] Cursor
>
> Add OrgX to your Cursor MCP configuration at
> `~/.cursor/mcp.json`:
>
> ```json theme={"dark"}
> {
>   "mcpServers": {
>     "orgx": {
>       "command": "npx",
>       "args": [
>         "mcp-remote",
>         "https://mcp.useorgx.com/mcp"
>       ]
>     }
>   }
> }
> ```
>
> Restart Cursor. On first use, `mcp-remote` opens the browser
> OAuth flow.

> [tab] Claude
>
> For a Claude custom connector, add:
>
> ```text theme={"dark"}
> https://mcp.useorgx.com/mcp
> ```
>
> For Claude Code, run:
>
> ```bash theme={"dark"}
> claude mcp add --transport http --scope user orgx https://mcp.useorgx.com/mcp
> claude mcp login orgx
> ```
>
> Complete OAuth in the browser when prompted. Team and Enterprise Claude
> workspaces may require an Owner to add the custom connector first.

> [tab] VS Code
>
> Run **MCP: Open User Configuration** from the Command Palette and add:
>
> ```json theme={"dark"}
> {
>   "servers": {
>     "orgx": {
>       "type": "http",
>       "url": "https://mcp.useorgx.com/mcp"
>     }
>   }
> }
> ```
>
> VS Code launches the OrgX OAuth flow on first use.

> [tab] OpenClaw
>
> Install the plugin, then complete browser pairing:
>
> ```bash theme={"dark"}
> openclaw plugins install @useorgx/openclaw-plugin
> ```
>
> Open the local plugin dashboard, choose **Connect OrgX**, and approve the
> connection. The OpenClaw bridge is a local connection mode; it is not the
> same transport as hosted remote MCP.
>
> [OpenClaw setup guide →](https://docs.useorgx.com/docs/guides/openclaw-plugin-setup.md)

For more clients, transport details, and recovery steps, see
[MCP Client Setup](https://docs.useorgx.com/docs/guides/cursor-mcp-setup.md).

## How OrgX works

OrgX turns a one-off prompt into a durable work episode:
**context → decision → execution → evidence**.

> [card] Shared workspace context
>
> Work stays inside a workspace boundary, so assistants can retrieve the
> right decisions, initiatives, artifacts, and active work without mixing
> unrelated company context.

> [card] Accountable execution
>
> Delegated work has an owner, lifecycle, approval boundary, and evidence
> trail. Completion is a claim until the relevant artifact or receipt is
> recorded.

| Object | What it holds | Why it matters |
| - | - | - |
| Workspace | The account and access boundary | Keeps context and permissions scoped |
| Initiative | A durable objective with work beneath it | Gives multi-step work a place to roll up |
| Task or agent run | Assigned execution and current state | Makes ownership and progress inspectable |
| Decision | A choice, rationale, and approval state | Preserves why the team moved forward |
| Artifact or receipt | The output and evidence of work | Makes “done” reviewable instead of implied |

## Establish context for the discovered profile

When discovery includes `orgx_bootstrap`, call it at the beginning
of a fresh session, after reconnecting, or before a multi-step workflow.
Status-only profiles such as `claude-directory` omit bootstrap:
use a permitted search, initiative pulse, or chronicle read to confirm context.

For bootstrap:

```json theme={"dark"}
{
  "workspace_id": "optional-workspace-id",
  "initiative_id": "optional-initiative-id"
}
```

The arguments are optional. The purpose is to establish context before the
assistant searches, delegates, changes state, or claims progress.

| Returned field | Use it for |
| - | - |
| `workspace` | Confirm the active workspace and account boundary |
| `granted_scopes` | Confirm the access the OAuth session actually received |
| `visible_tools` | Confirm the selected profile and scope expose the tools you need |
| Routing guidance | Decide whether to search, inspect, plan, delegate, or ask for approval |

> [!TIP]
>
> If the workspace is wrong or the required tool is absent, stop and reconnect
> or choose the correct profile and access. Do not compensate by guessing IDs
> or claiming work happened elsewhere.

## The durable work loop

**1. Start from context**

Bootstrap the session and confirm the workspace, scopes, and visible tools.

**2. Find the relevant record**

Use `orgx_search` for a question or `orgx_inspect`
when you already know the record ID.

**3. Choose the next move**

Use `orgx_recommend` or `orgx_plan` when priority,
sequencing, or acceptance criteria are unclear.

**4. Act within the boundary**

Use `orgx_decide`, `orgx_spawn`,
`scaffold_initiative`, or `orgx_act` according to
the user's intent and granted access.

**5. Leave proof behind**

Attach the artifact or evidence with `orgx_attach` and record a
completion receipt with `orgx_submit_receipt` when the work is
actually done.

## Tools

Your assistant chooses these tools automatically. Use this table when you need
the exact routing decision, minimum input, or result to expect.

| Tool | Use it for | Minimum input | Result |
| - | - | - | - |
| `orgx_bootstrap` | Establish session and routing context | Optional workspace or initiative ID | Workspace, scopes, visible tools, and guidance |
| `orgx_search` | Find decisions, artifacts, initiatives, tasks, or context | Query or typed filters | Matching records with enough context to choose the next call |
| `orgx_inspect` | Read one known record deeply | Record type and ID | The record plus related work, decisions, or evidence |
| `orgx_recommend` | Recover after time away or prioritize | Entity or workspace context | Ranked next actions, gaps, or blockers |
| `orgx_decide` | Record, list, approve, or reject a decision | Action plus decision fields or ID | Decision state and approval history |
| `orgx_spawn` | Assign work to a specialist agent | Agent plus task instructions | Queued work, owner, run, budget, and guardrail outcome |
| `orgx_act` | Start, block, complete, or change lifecycle state | Entity ID, action, and reason when needed | Updated state or a structured validation error |
| `orgx_attach` | Connect an artifact or evidence to work | Parent ID plus artifact or evidence | Linked artifact/evidence record |
| `orgx_submit_receipt` | Record proof of completed work | Work/run ID plus outcome and evidence | Receipt status and validation result |
| `get_agent_status` | See what agents are doing now | Optional agent or initiative filter | Running, idle, blocked, and completed work |
| `get_initiative_pulse` | Check initiative health | Initiative ID | Progress, milestones, blockers, and recent activity |

> [!TIP]
>
> The full reference is generated from the tool contracts and includes
> deprecated aliases, exact schemas, required scopes, profiles, and response
> examples. Use [MCP Tools Reference](https://docs.useorgx.com/docs/api/mcp-tools.md) when implementing a
> client or debugging a validation error.

## Common workflows

> [card] Continue existing work
>
> Call `orgx_bootstrap`, then
> `orgx_search`, `orgx_inspect`, and
> `orgx_recommend`. Start from the existing record instead of
> opening a parallel task.

> [card] Record a decision
>
> Use `orgx_decide` with the choice, rationale, owner, and
> initiative when known. Ask for approval when the decision changes a
> consequential plan.

> [card] Delegate work
>
> Use `orgx_spawn` only when the user wants an agent to do the
> work. Include the expected artifact, deadline, quality bar, and initiative
> or task binding when available.

> [card] Complete with proof
>
> Do not infer completion from a queued or successful tool response. Attach
> the output, submit a receipt, and let the user review the resulting
> evidence.

## Profiles and access

The endpoint profile controls discovery: it determines which tools the client
sees. OAuth scopes control which resource actions the connection can perform.
Workspace membership still determines which records the user can reach.

### Tool profiles

| Profile | Best for |
| - | - |
| `v2` | Default compact public surface |
| `chatgpt` | ChatGPT-compatible tools and interactive UI |
| `memory` | Search, context, decisions, and receipts |
| `commander` | Human-led planning, delegation, and approvals |
| `planner` | Initiative planning and decision handoffs |
| `executor` | Agent execution, evidence, and receipts |
| `observer` | Monitoring and reporting |

Use the bare endpoint for most clients. Append
`?profile=NAME` only when a smaller surface helps the workflow. For
example:

```text theme={"dark"}
https://mcp.useorgx.com/mcp?profile=observer
```

Reconnect the client after changing the profile so it refreshes
`tools/list`.

### OAuth access presets

> [card] Read
>
> View decisions, agents, initiatives, artifacts, receipts, and memory
> without changing work.

> [card] Operate
>
> Read and change work, including decisions, delegated agents, initiatives,
> and evidence.

> [card] Customize
>
> Choose read or operate access separately for each resource.

### OAuth scopes

| Scope | Grants |
| - | - |
| `decisions:read` | View decisions, approvals, and history |
| `decisions:write` | Create, approve, reject, or update decisions |
| `agents:read` | View agent work, status, and execution history |
| `agents:write` | Delegate, hand off, retry, pause, resume, or cancel work |
| `initiatives:read` | View initiatives, work state, artifacts, and receipts |
| `initiatives:write` | Create or update work and attach artifacts or proof |
| `memory:read` | Search and recall organizational memory |
| `offline_access` | Allow the client to refresh access after the current session |

> [!WARNING]
>
> OrgX evaluates the required scope when a tool runs. A connection can
> discover a tool and still receive a structured `403
> insufficient_scope` response when the OAuth grant is too narrow.
> Reconnect and authorize the missing resource action; do not retry the same
> call unchanged.

## Interactive widgets and resources

Clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)
can render OrgX views inside the conversation.

| Kind | Name or URI | What it returns or opens |
| - | - | - |
| Resource | `orgx://initiative/` | Initiative details with milestones and tasks as markdown |
| Widget | `ui://widget/decisions.html` | Pending decisions and approval actions |
| Widget | `ui://widget/agent-status.html` | Current agent status and activity |
| Widget | `ui://widget/search-results.html` | Search results for organizational memory |
| Widget | `ui://widget/initiative-pulse.html` | Initiative health and progress |
| Widget | `ui://widget/task-spawned.html` | Confirmation that agent work was assigned |
| Prompt | `create-roadmap` | A guided initiative, milestone, and task creation flow |
| Prompt | `plan_feature` | A planning flow with improvement suggestions |
| Prompt | `get_my_patterns` | Learned planning patterns and skills |

> [!NOTE]
>
> A widget is a rendered view of tool output, not a second source of truth.
> Re-call the underlying read tool when freshness matters—especially after a
> state change, reconnect, or long-running agent run. Hosts without MCP Apps
> support still receive the structured tool result.

## MCP or REST?

| Use MCP when you need | Use REST when you need |
| - | - |
| A person or assistant working interactively | A server-to-server integration |
| OAuth, client-managed context, and inline widgets | A versioned contract, webhooks, or batch processing |
| Natural-language routing across OrgX tools | Explicit idempotency, pagination, and HTTP error handling |

The [MCP ↔ REST parity page](https://docs.useorgx.com/docs/api/mcp-rest-parity.md) maps the surfaces and
documents the canonical v1 routes.

## Troubleshooting

> [accordion] The client connects but tools are missing
>
> Call `orgx_bootstrap`, inspect `visible_tools`, and
> confirm the endpoint profile. Reconnect after changing a profile or OAuth
> grant so the client refreshes its tool list.

> [accordion] A call returns 403 insufficient\_scope
>
> The OAuth grant does not include the resource action required by the tool.
> Reconnect and choose the missing access, or use a read-only workflow.

> [accordion] The workspace or results are wrong
>
> Stop before writing. Call `orgx_bootstrap` with the intended
> workspace, then use `orgx_search` or
> `orgx_inspect` to verify the record boundary.

> [accordion] A widget looks stale
>
> Treat the widget as a snapshot. Re-call the corresponding read or status
> tool and compare the returned state before telling the user that work is
> complete, blocked, or still running.

> [accordion] An agent is not producing an outcome
>
> Check `get_agent_status`, inspect the bound task or initiative,
> and look for a pending decision or blocker. A queued run is not evidence
> that the final artifact exists.

> [accordion] You need to use the local OpenClaw bridge
>
> Confirm the OpenClaw gateway is running and use the local bridge setup
> guide. The hosted URL and local bridge have overlapping tools but are not
> identical transports or surfaces.

## Next steps

> [card] [MCP Client Setup](https://docs.useorgx.com/docs/guides/cursor-mcp-setup.md)
>
> Configure Claude, Cursor, ChatGPT, VS Code, OpenClaw, or another remote
> client.

> [card] [MCP Tools Reference](https://docs.useorgx.com/docs/api/mcp-tools.md)
>
> Browse exact inputs, scopes, profiles, and response examples.

> [card] [Agent Quickstart](https://docs.useorgx.com/docs/agent-ops/agent-quickstart.md)
>
> Run a first workflow from context through accountable completion.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.