> ## Documentation Index
> Fetch the complete documentation index at: https://docsgetmyordo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect Ordo to MCP clients like Cursor and Claude Desktop using the official Ordo MCP server.

Ordo supports the Model Context Protocol (MCP) in two ways:

1. **Built-in HTTP endpoint** — every Ordo instance exposes `/api/mcp` out of the box. No extra setup, no extra process.
2. **Stdio package** (`@Ordo/mcp`) — a local stdio server for clients that prefer stdio transport.

Both offer the same tools for managing workspaces, projects, tasks, comments, and labels.

## Built-in HTTP endpoint

Every Ordo API instance ships with a Streamable HTTP MCP endpoint. This is the recommended approach for self-hosted deployments.

Point your MCP client at:

```
https://your-Ordo-instance.com/api/mcp
```

On first connect, you will be redirected to Ordo's login page. After you sign in, all MCP tools run as your authenticated user.

The endpoint implements OAuth 2.1 with PKCE for authentication. Discovery metadata is available at:

* `/.well-known/oauth-protected-resource/api/mcp`
* `/.well-known/oauth-authorization-server/api`

## Stdio package

The `@Ordo/mcp` package runs a local stdio MCP server and authenticates with Ordo using device authorization. Use this when your MCP client requires stdio transport.

### Prerequisites

* Node.js 20 or newer
* A running Ordo API
* Access to the Ordo web app to approve device login

By default, self-hosted Ordo allows both `Ordo-cli` and `Ordo-mcp` as device auth client IDs.

### Install and register

Use the recommended interactive installer:

```bash theme={null}
npx @Ordo/mcp
```

The installer lets you choose where to register the server configuration:

* Cursor (user-wide)
* Cursor (project-level)
* Claude Desktop
* Custom JSON config path

You can also run the explicit install command:

```bash theme={null}
Ordo-mcp install --target cursor-user -y
```

Use `--help` to see all available targets and flags:

```bash theme={null}
Ordo-mcp install --help
```

### Point to a self-hosted instance

When generating config, pass your Ordo base URL:

```bash theme={null}
Ordo-mcp install --target cursor-user -y --api-url https://Ordo.example.com
```

Or set it via environment variable:

| Variable | Description |
| - | - |
| `Ordo_API_URL` | Ordo API origin. Default: `http://localhost:1337`. Do not include `/api`. |
| `Ordo_MCP_CLIENT_ID` | Device auth client ID. Default: `Ordo-mcp`. |

If you override `Ordo_MCP_CLIENT_ID`, make sure it is included in [`DEVICE_AUTH_CLIENT_IDS`](https://docsgetmyordo.mintlify.site/core/installation/environment-variables).

### Authentication flow

On the first tool call that needs Ordo access, the MCP server:

1. Requests a device code from Ordo
2. Prints a verification URL and user code
3. Opens the browser when possible
4. Polls until you approve sign-in
5. Stores credentials in `~/.config/Ordo-mcp/credentials.json`

## Available tools

Both the HTTP endpoint and stdio package expose the same tools:

* Session: `whoami`, `list_workspaces`
* Projects: `list_projects`, `get_project`, `create_project`, `update_project`
* Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `update_task_status`
* Comments: `list_task_comments`, `create_task_comment`
* Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`

## Debugging

To run the stdio server directly:

```bash theme={null}
npx @Ordo/mcp serve
```

When running from source in this monorepo:

```bash theme={null}
pnpm --filter @Ordo/mcp run build
pnpm --filter @Ordo/mcp run start
```


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