> ## 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 Client Setup

> Connect OrgX MCP from ChatGPT, Cursor, Claude, VS Code, and other remote MCP clients.

OrgX exposes a **Model Context Protocol (MCP)** server that integrates with
ChatGPT, Cursor, Claude, VS Code, and other remote MCP clients. This gives
agents shared organizational memory for decisions, artifacts, tasks,
approvals, and project execution context without leaving the client you already
use.

<Info>
  Use `https://mcp.useorgx.com/mcp` as the default hosted OrgX MCP URL. It is
  the streamable HTTP endpoint for remote MCP clients. ChatGPT Developer Mode is
  the exception: use `https://mcp.useorgx.com/mcp?profile=chatgpt`. Use
  `https://mcp.useorgx.com/sse` only when a legacy client explicitly asks for
  SSE.
</Info>

## Prerequisites

<Check>An OrgX account at [useorgx.com](https://useorgx.com)</Check>
<Check>Node.js 18+ installed</Check>

<Check>
  A supported remote MCP client (ChatGPT, Cursor, Claude, VS Code, or
  equivalent)
</Check>

## Quick Setup

<Tabs>
  <Tab title="OpenClaw (Recommended)">
    Install the plugin, then complete browser pairing:

    ```bash theme={"dark"}
    openclaw plugins install @useorgx/openclaw-plugin
    ```

    Then open the plugin dashboard, click **Connect OrgX**, and approve in your
    browser.

    [Full OpenClaw setup guide →](/docs/guides/openclaw-plugin-setup)
  </Tab>

  <Tab title="ChatGPT">
    ### Step 1: Enable Developer Mode

    Open [chatgpt.com/plugins](https://chatgpt.com/plugins), then enable
    **Developer Mode** in **Settings → Security**.

    ### Step 2: Add OrgX

    Use:

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

    ### Step 3: Authenticate

    ChatGPT will send you through the OrgX OAuth flow in-browser. After that,
    you can use OrgX naturally in chat.

    <Info>
      This connection uses ChatGPT Developer Mode and the `chatgpt` tool
      profile.
    </Info>

    <Tip>
      For ChatGPT-specific UX, widget examples, and permissions, see the
      [ChatGPT integration guide](/docs/guides/chatgpt-integration).
    </Tip>
  </Tab>

  <Tab title="Cursor IDE">
    ### Step 1: Configure Cursor

    Edit your Cursor MCP configuration at `~/.cursor/mcp.json`:

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

    ### Step 2: Restart Cursor

    Restart Cursor to load the MCP server. On first use, `mcp-remote` will open your browser for OAuth sign-in. Approve the connection and you're set.
  </Tab>

  <Tab title="Claude">
    ### Claude.ai or Claude Desktop custom connector

    On an individual Free, Pro, or Max plan, open **Customize → Connectors → +
    → Add custom connector** and use:

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

    Or open the
    [prefilled OrgX connector form](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=OrgX\&connectorUrl=https%3A%2F%2Fmcp.useorgx.com%2Fmcp).
    On Team or Enterprise, an Owner or Primary Owner must first add OrgX under
    **Organization settings → Connectors → Add → Custom → Web**. Members then
    connect it from **Customize → Connectors**.

    Claude will open the OrgX OAuth flow in your browser.

    ### Claude Code direct MCP

    ```bash theme={"dark"}
    claude mcp add --transport http --scope user orgx https://mcp.useorgx.com/mcp
    claude mcp login orgx
    ```

    ### Claude Code self-hosted plugin

    ```bash theme={"dark"}
    npx -y @useorgx/wizard@latest plugins add claude
    ```

    The self-hosted plugin provides static skills and commands plus
    native-OAuth MCP. It does not install transcript/context telemetry hooks or
    dynamic skill/agent sync.

    <Info>
      For hosted MCP, use Claude's Connectors UI or connect directly from
      Claude Code. The self-hosted plugin is a separate option for static
      skills and commands.
    </Info>
  </Tab>

  <Tab title="VS Code">
    ### Step 1: Open VS Code MCP config

    Run **MCP: Open User Configuration** from the Command Palette.

    ### Step 2: Add OrgX

    ```json theme={"dark"}
    {
      "servers": {
        "orgx": {
          "type": "http",
          "url": "https://mcp.useorgx.com/mcp"
        }
      }
    }
    ```

    ### Step 3: Authenticate

    On first use, VS Code will launch the OrgX OAuth flow in your browser.
  </Tab>

  <Tab title="Other MCP Clients">
    If your client supports **remote MCP over HTTP/SSE + OAuth**, start with:

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

    If the client asks for a specific transport route, use:

    * `https://mcp.useorgx.com/mcp` for streamable HTTP
    * `https://mcp.useorgx.com/sse` for SSE

    Use the SSE route only for clients that do not yet support streamable HTTP.
  </Tab>
</Tabs>

## Supported Clients At A Glance

| Surface                        | Setup style                      | Availability | Best for                                         |
| ------------------------------ | -------------------------------- | ------------ | ------------------------------------------------ |
| ChatGPT Developer Mode         | `?profile=chatgpt`               | Available    | Conversational approvals + organizational memory |
| Cursor                         | `mcp-remote` + bare `/mcp`       | Available    | IDE-assisted coding + delivery                   |
| Claude custom connector        | Connectors UI + bare `/mcp`      | Available    | Conversational planning + review                 |
| Claude Code direct MCP         | `claude mcp add` + bare `/mcp`   | Available    | Terminal agent workflows                         |
| Claude Code self-hosted plugin | OrgX wizard                      | Available    | Static skills and commands + native-OAuth MCP    |
| VS Code                        | HTTP server config + bare `/mcp` | Available    | Planning and delivery inside editor              |
| Other remote MCP clients       | Root URL + OAuth                 | Varies       | Generic MCP interoperability                     |

## Verify Connection

After authorizing, verify the MCP server is working by calling:

```json theme={"dark"}
{ "tool": "orgx_bootstrap", "args": {} }
```

You should receive the connected workspace context and recommended next action.

## First Calls That Prove The Integration

Once connected, these calls prove the integration is healthy:

1. `orgx_bootstrap`
2. `orgx_search` with the query `recent decisions`
3. `orgx_recommend` for the next action
4. `orgx_decide action=list_pending` to inspect pending approvals without changing them

After that, and only in a workspace where you have explicitly authorized
writes, useful write calls include:

* `orgx_decide` to save a durable team decision
* `orgx_spawn` to dispatch focused work
* `scaffold_initiative` to create a real IWMT hierarchy
* `orgx_attach` to attach evidence or artifacts
* `orgx_submit_receipt` to record proof of completed work

## Widgets & Resources

OrgX MCP also exposes **resources** and **widgets**:

| Resource URI                        | Description                         |
| ----------------------------------- | ----------------------------------- |
| `orgx://initiative/{id}`            | Full initiative details as markdown |
| `ui://widget/decisions.html`        | Decision widget HTML                |
| `ui://widget/agent-status.html`     | Agent status widget HTML            |
| `ui://widget/initiative-pulse.html` | Initiative pulse widget HTML        |
| `ui://widget/morning-brief.html`    | Morning brief widget HTML           |

Clients that support MCP Apps rendering can show OrgX decision, search, agent
status, initiative pulse, task dispatch, and morning brief widgets inline.

## Transport Options

The OrgX MCP server supports two transports:

| Transport | Endpoint                      | Use Case                             |
| --------- | ----------------------------- | ------------------------------------ |
| **HTTP**  | `https://mcp.useorgx.com/mcp` | Recommended streamable HTTP endpoint |
| **SSE**   | `https://mcp.useorgx.com/sse` | Legacy SSE endpoint                  |

Both transports use the same OAuth 2.1 browser authorization flow when the
client supports remote MCP OAuth.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused">
    * Verify the MCP server URL is correct
    * Reconnect the MCP server entry in your client to refresh OAuth state
    * Ensure you have network access to `mcp.useorgx.com`
  </Accordion>

  <Accordion title="Authentication failed">
    * Disconnect and reconnect OrgX in your MCP client to restart OAuth - Complete
      browser sign-in and grant access to the correct workspace - Verify your OrgX
      account is active
  </Accordion>

  <Accordion title="Tools not appearing">
    * Restart your IDE after updating `mcp.json` - Check the MCP config file for
      JSON syntax errors - Run the health check command to verify connectivity
  </Accordion>

  <Accordion title="Permission denied on tool calls">
    * Some tools require write scopes (for example, decision approvals)
    * Reconnect and approve broader scopes if prompted
    * Check that your OrgX role has the required permissions
  </Accordion>
</AccordionGroup>

## Security Notes

* OAuth access tokens are short-lived and refreshed by your MCP client
* All traffic is encrypted via HTTPS
* OAuth grants are scoped to specific permissions
* Revoke access by disconnecting OrgX from your MCP client or OrgX settings

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Protocol Reference" icon="book" href="/docs/api/mcp-protocol">
    Deep dive into the MCP protocol implementation.
  </Card>

  <Card title="MCP Tools Reference" icon="wrench" href="/docs/api/mcp-tools">
    Complete API documentation for all tools.
  </Card>
</CardGroup>