> ## 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. Use
  `https://mcp.useorgx.com/sse` only when a legacy client explicitly asks for
  SSE.
</Info>

## Questions This Page Answers

* Which OrgX MCP URL should I use in each client?
* Which clients render OrgX widgets vs plain tool output?
* What are the fastest first calls to verify the integration is healthy?

## 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)">
    The fastest path — handles auth and config automatically in 60 seconds:

    ```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. Done.

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

  <Tab title="ChatGPT">
    ### Step 1: Open Apps & Connectors

    In ChatGPT, open **Settings → Apps & Connectors** and add a custom remote
    MCP server.

    ### Step 2: Add OrgX

    Use:

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

    ### Step 3: Authenticate

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

    <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">
    ### Step 1: Open Connectors

    In Claude or Claude Desktop, open **Settings → Connectors** and choose to
    add a custom remote MCP connector.

    ### Step 2: Add OrgX

    Use:

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

    ### Step 3: Authenticate

    Claude will open the OrgX OAuth flow in your browser.

    <Warning>
      Anthropic’s current remote-connector flow for hosted MCP servers should
      use the Connectors UI. Do not document hosted OrgX as a remote server you
      add directly via `claude_desktop_config.json`.
    </Warning>
  </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>

  <Tab title="Local Development">
    For local development, you can run the MCP server locally:

    ### Step 1: Clone and Setup

    ```bash theme={"dark"}
    cd workers/orgx-mcp
    pnpm install
    cp .dev.vars.example .dev.vars
    # Edit .dev.vars with your credentials
    ```

    ### Step 2: Start Local Server

    ```bash theme={"dark"}
    pnpm dev
    # Server runs at http://127.0.0.1:8787
    ```

    ### Step 3: Configure for Local

    Update your MCP config to point to localhost:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "orgx-local": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "http://127.0.0.1:8787/"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Supported Clients At A Glance

| Client                   | Setup style         | Widgets               | Best for                                         |
| ------------------------ | ------------------- | --------------------- | ------------------------------------------------ |
| ChatGPT                  | Apps & Connectors   | Yes                   | Conversational approvals + organizational memory |
| Cursor                   | `mcp-remote` config | Yes                   | IDE-assisted coding + delivery                   |
| Claude                   | Connectors          | Yes                   | Conversational planning + review                 |
| VS Code                  | HTTP server config  | Yes                   | Planning and delivery inside editor              |
| Other remote MCP clients | Root URL + OAuth    | Usually text fallback | Generic MCP interoperability                     |

## Verify Connection

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

```json theme={"dark"}
{ "tool": "workspace", "args": { "action": "get" } }
```

You should see your workspace name and ID.

## First Calls That Prove The Integration

Once connected, these calls prove the integration is healthy:

1. `workspace action=get`
2. `orgx_recommend view=summary`
3. `orgx_search query="recent decisions" scope=decisions`

After that, the highest-value first write calls are:

* `orgx_decide` to save a durable team decision
* `orgx_decide action=list` to review pending human approvals
* `orgx_spawn` to dispatch focused work
* `orgx_recommend` to get initiative health and blockers
* `scaffold_initiative` to create a real IWMT hierarchy
* `orgx_decide` / `orgx_decide` to run the human-in-the-loop loop
* `orgx_search` when you need the lower-level memory search directly

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