> ## 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](/docs/api/mcp-tools) 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.

<Info>
  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. For ChatGPT Developer Mode, use
  [https://mcp.useorgx.com/mcp?profile=chatgpt](https://mcp.useorgx.com/mcp?profile=chatgpt).
</Info>

<Steps>
  <Step title="Add the endpoint">
    Paste the hosted URL into your MCP client or use the client-specific setup
    below.
  </Step>

  <Step title="Approve the connection">
    Complete the browser sign-in and review the workspace plus requested
    resource access before approving.
  </Step>

  <Step title="Confirm the session">
    Call <code>orgx\_bootstrap</code>. Do not start work until the returned
    workspace and visible tools match what you intended to authorize.
  </Step>
</Steps>

<Check>
  A healthy connection has a valid OAuth session, the expected workspace, a
  non-empty <code>granted\_scopes</code> value, and the tools required for the
  current workflow in <code>visible\_tools</code>.
</Check>

## Quick setup by client

<Tabs>
  <Tab title="ChatGPT">
    Enable Developer Mode in ChatGPT under **Settings → Security**, then add a
    custom connector with:

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

    Complete the OrgX OAuth flow in your browser. See the
    [ChatGPT integration guide](/docs/guides/chatgpt-integration) for the
    ChatGPT-specific connection and widget checks.
  </Tab>

  <Tab title="Cursor">
    Add OrgX to your Cursor MCP configuration at
    <code>\~/.cursor/mcp.json</code>:

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

    Restart Cursor. On first use, <code>mcp-remote</code> opens the browser
    OAuth flow.
  </Tab>

  <Tab title="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>

  <Tab title="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>

  <Tab title="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 →](/docs/guides/openclaw-plugin-setup)
  </Tab>
</Tabs>

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

## How OrgX works

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

<CardGroup cols={2}>
  <Card title="Shared workspace context" icon="server">
    Work stays inside a workspace boundary, so assistants can retrieve the
    right decisions, initiatives, artifacts, and active work without mixing
    unrelated company context.
  </Card>

  <Card title="Accountable execution" icon="check">
    Delegated work has an owner, lifecycle, approval boundary, and evidence
    trail. Completion is a claim until the relevant artifact or receipt is
    recorded.
  </Card>
</CardGroup>

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

## Start every session with bootstrap

Call <code>orgx\_bootstrap</code> at the beginning of a fresh session, after
reconnecting, or before a multi-step workflow:

```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                                                             |
| ---------------------------- | ---------------------------------------------------------------------- |
| <code>workspace</code>       | Confirm the active workspace and account boundary                      |
| <code>granted\_scopes</code> | Confirm the access the OAuth session actually received                 |
| <code>visible\_tools</code>  | Confirm the selected profile and scope expose the tools you need       |
| Routing guidance             | Decide whether to search, inspect, plan, delegate, or ask for approval |

<Check>
  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.
</Check>

## The durable work loop

<Steps>
  <Step title="Start from context">
    Bootstrap the session and confirm the workspace, scopes, and visible tools.
  </Step>

  <Step title="Find the relevant record">
    Use <code>orgx\_search</code> for a question or <code>orgx\_inspect</code>
    when you already know the record ID.
  </Step>

  <Step title="Choose the next move">
    Use <code>orgx\_recommend</code> or <code>orgx\_plan</code> when priority,
    sequencing, or acceptance criteria are unclear.
  </Step>

  <Step title="Act within the boundary">
    Use <code>orgx\_decide</code>, <code>orgx\_spawn</code>,
    <code>scaffold\_initiative</code>, or <code>orgx\_act</code> according to
    the user's intent and granted access.
  </Step>

  <Step title="Leave proof behind">
    Attach the artifact or evidence with <code>orgx\_attach</code> and record a
    completion receipt with <code>orgx\_submit\_receipt</code> when the work is
    actually done.
  </Step>
</Steps>

## 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                                                       |
| ----------------------------------- | --------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| <code>orgx\_bootstrap</code>        | Establish session and routing context                     | Optional workspace or initiative ID       | Workspace, scopes, visible tools, and guidance               |
| <code>orgx\_search</code>           | Find decisions, artifacts, initiatives, tasks, or context | Query or typed filters                    | Matching records with enough context to choose the next call |
| <code>orgx\_inspect</code>          | Read one known record deeply                              | Record type and ID                        | The record plus related work, decisions, or evidence         |
| <code>orgx\_recommend</code>        | Recover after time away or prioritize                     | Entity or workspace context               | Ranked next actions, gaps, or blockers                       |
| <code>orgx\_decide</code>           | Record, list, approve, or reject a decision               | Action plus decision fields or ID         | Decision state and approval history                          |
| <code>orgx\_spawn</code>            | Assign work to a specialist agent                         | Agent plus task instructions              | Queued work, owner, run, budget, and guardrail outcome       |
| <code>orgx\_act</code>              | Start, block, complete, or change lifecycle state         | Entity ID, action, and reason when needed | Updated state or a structured validation error               |
| <code>orgx\_attach</code>           | Connect an artifact or evidence to work                   | Parent ID plus artifact or evidence       | Linked artifact/evidence record                              |
| <code>orgx\_submit\_receipt</code>  | Record proof of completed work                            | Work/run ID plus outcome and evidence     | Receipt status and validation result                         |
| <code>get\_agent\_status</code>     | See what agents are doing now                             | Optional agent or initiative filter       | Running, idle, blocked, and completed work                   |
| <code>get\_initiative\_pulse</code> | 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](/docs/api/mcp-tools) when implementing a
  client or debugging a validation error.
</Tip>

## Common workflows

<CardGroup cols={2}>
  <Card title="Continue existing work" icon="rotate">
    Call <code>orgx\_bootstrap</code>, then
    <code>orgx\_search</code>, <code>orgx\_inspect</code>, and
    <code>orgx\_recommend</code>. Start from the existing record instead of
    opening a parallel task.
  </Card>

  <Card title="Record a decision" icon="lightbulb">
    Use <code>orgx\_decide</code> with the choice, rationale, owner, and
    initiative when known. Ask for approval when the decision changes a
    consequential plan.
  </Card>

  <Card title="Delegate work" icon="users">
    Use <code>orgx\_spawn</code> 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>

  <Card title="Complete with proof" icon="check">
    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.
  </Card>
</CardGroup>

## 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                                      |
| ---------------------- | --------------------------------------------- |
| <code>v2</code>        | Default compact public surface                |
| <code>chatgpt</code>   | ChatGPT-compatible tools and interactive UI   |
| <code>memory</code>    | Search, context, decisions, and receipts      |
| <code>commander</code> | Human-led planning, delegation, and approvals |
| <code>planner</code>   | Initiative planning and decision handoffs     |
| <code>executor</code>  | Agent execution, evidence, and receipts       |
| <code>observer</code>  | Monitoring and reporting                      |

Use the bare endpoint for most clients. Append
<code>?profile=NAME</code> 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
<code>tools/list</code>.

### OAuth access presets

<CardGroup cols={3}>
  <Card title="Read" icon="eye">
    View decisions, agents, initiatives, artifacts, receipts, and memory
    without changing work.
  </Card>

  <Card title="Operate" icon="bolt">
    Read and change work, including decisions, delegated agents, initiatives,
    and evidence.
  </Card>

  <Card title="Customize" icon="sliders">
    Choose read or operate access separately for each resource.
  </Card>
</CardGroup>

### OAuth scopes

| Scope                          | Grants                                                       |
| ------------------------------ | ------------------------------------------------------------ |
| <code>decisions:read</code>    | View decisions, approvals, and history                       |
| <code>decisions:write</code>   | Create, approve, reject, or update decisions                 |
| <code>agents:read</code>       | View agent work, status, and execution history               |
| <code>agents:write</code>      | Delegate, hand off, retry, pause, resume, or cancel work     |
| <code>initiatives:read</code>  | View initiatives, work state, artifacts, and receipts        |
| <code>initiatives:write</code> | Create or update work and attach artifacts or proof          |
| <code>memory:read</code>       | Search and recall organizational memory                      |
| <code>offline\_access</code>   | 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 <code>403
  insufficient\_scope</code> response when the OAuth grant is too narrow.
  Reconnect and authorize the missing resource action; do not retry the same
  call unchanged.
</Warning>

## 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 | <code>orgx://initiative/{id}</code>            | Initiative details with milestones and tasks as markdown |
| Widget   | <code>ui://widget/decisions.html</code>        | Pending decisions and approval actions                   |
| Widget   | <code>ui://widget/agent-status.html</code>     | Current agent status and activity                        |
| Widget   | <code>ui://widget/search-results.html</code>   | Search results for organizational memory                 |
| Widget   | <code>ui://widget/initiative-pulse.html</code> | Initiative health and progress                           |
| Widget   | <code>ui://widget/task-spawned.html</code>     | Confirmation that agent work was assigned                |
| Prompt   | <code>create-roadmap</code>                    | A guided initiative, milestone, and task creation flow   |
| Prompt   | <code>plan\_feature</code>                     | A planning flow with improvement suggestions             |
| Prompt   | <code>get\_my\_patterns</code>                 | Learned planning patterns and skills                     |

<Info>
  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.
</Info>

## 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](/docs/api/mcp-rest-parity) maps the surfaces and
documents the canonical v1 routes.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client connects but tools are missing">
    Call <code>orgx\_bootstrap</code>, inspect <code>visible\_tools</code>, and
    confirm the endpoint profile. Reconnect after changing a profile or OAuth
    grant so the client refreshes its tool list.
  </Accordion>

  <Accordion title="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>

  <Accordion title="The workspace or results are wrong">
    Stop before writing. Call <code>orgx\_bootstrap</code> with the intended
    workspace, then use <code>orgx\_search</code> or
    <code>orgx\_inspect</code> to verify the record boundary.
  </Accordion>

  <Accordion title="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>

  <Accordion title="An agent is not producing an outcome">
    Check <code>get\_agent\_status</code>, 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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="MCP Client Setup" icon="code" href="/docs/guides/cursor-mcp-setup">
    Configure Claude, Cursor, ChatGPT, VS Code, OpenClaw, or another remote
    client.
  </Card>

  <Card title="MCP Tools Reference" icon="wrench" href="/docs/api/mcp-tools">
    Browse exact inputs, scopes, profiles, and response examples.
  </Card>

  <Card title="Agent Quickstart" icon="bolt" href="/docs/agent-ops/agent-quickstart">
    Run a first workflow from context through accountable completion.
  </Card>
</CardGroup>