# Othos MCP

`@othos-io/othos-mcp` is a Model Context Protocol (MCP) server for the [Othos Platform](https://app.othos.com.br). It lets AI coding agents and MCP clients authenticate with Othos and work directly with organizations, projects, columns, and tickets.

This package is designed for two main use cases:

- Local `stdio` usage with coding agents such as Codex, Claude Code, and Cursor.
- Remote Streamable HTTP deployments protected by OAuth bearer tokens.

## Choose The Right Setup

For most new users, the correct setup is the local `stdio` package installed
with `add-mcp`.

Use local `stdio` when:

- you are installing the MCP into Codex, Cursor, Claude Code, or a similar
  desktop coding agent
- you want to use `othos_auth_connect`
- you want the MCP process to open a localhost callback and finish auth on your
  machine

Use the remote HTTP endpoint only when:

- your MCP client already supports transport-level OAuth or bearer auth for
  remote MCP servers
- you already know how the client will obtain and attach the Authorization
  header for `https://mcp.othos.com.br/mcp`

If you are unsure, use local `stdio`.

## What This Server Can Do

- Authenticate to Othos with a browser-based OAuth flow, a bearer token, or cookie-based session auth.
- Inspect the current authentication state and active organization context.
- List, create, update, and delete projects and columns.
- List, create, update, move, assign, unassign, and delete tickets.
- Return ticket data in an agent-friendly fixed text template when you want clean chat output.
- Run either as a local MCP server over `stdio` or as a deployed MCP server over HTTP.

## Getting Started

### Install with `add-mcp`

Install the MCP server for all detected coding agents in the current project:

```bash
npx add-mcp @othos-io/othos-mcp@latest
```

Add `-y` to skip prompts and `-g` to install globally.

### Manual installation

If your MCP client expects a manual config, use:

```json
{
  "mcpServers": {
    "othos-mcp": {
      "command": "npx",
      "args": ["-y", "@othos-io/othos-mcp@latest"]
    }
  }
}
```

### Codex CLI

```bash
codex mcp add othos-mcp -- npx -y @othos-io/othos-mcp@latest
```

This is the recommended path for a new user.

## Quick Start

For local `stdio` usage, the recommended flow is:

1. Install the server in your MCP client.
2. Start a session and call `othos_auth_connect`.
3. Open the returned authorization URL in your browser.
4. Approve the connection in Othos.
5. Start using tools such as `othos_organization_list`, `othos_project_list`, and `othos_ticket_create`.

> [!NOTE]
> If you call a protected tool without valid authentication, the server returns an auth-required response that includes the authorization link. After approval in the browser, the local MCP process receives the loopback callback and stores the bearer token automatically.

## New User Flow

The intended first-run experience is:

1. Install the npm package into the MCP client using `add-mcp`.
2. Let the MCP client launch the package locally over `stdio`.
3. Call `othos_auth_connect`.
4. Open the returned browser URL.
5. Approve access in Othos.
6. Return to the MCP client and start using organization, project, column, and
   ticket tools.

The intended first-run experience is not:

1. connect directly to `https://mcp.othos.com.br/mcp` as an unauthenticated
   HTTP client
2. expect `othos_auth_connect` to bootstrap auth on that remote transport

That remote path requires transport-level auth before the MCP session is even
available.

## Authentication

### Recommended: browser authorization

`othos_auth_connect` starts a local OAuth authorization flow and is the best default for local MCP usage.

It can:

- Open a browser-based approval flow.
- Listen on a localhost callback URL for the browser redirect.
- Exchange the authorization code for an Othos bearer token.
- Persist the token to disk automatically.

By default, local `stdio` sessions save the token to:

- `$XDG_CONFIG_HOME/othos-mcp/personal-token`, or
- `$HOME/.config/othos-mcp/personal-token`

You can override that with `OTHOS_PERSONAL_TOKEN_PATH` or the `savePath` argument.

### Direct personal token

If you already have a bearer token, you can provide it directly:

```bash
export OTHOS_PERSONAL_TOKEN="othos_pat_v1...."
```

You can also set it from inside the MCP session with `othos_auth_set_personal_token`.

When a bearer token is available, the server sends it to the Othos API as:

```http
Authorization: Bearer <token>
```

### Cookie-based compatibility

Cookie-based auth is still supported for compatibility:

- `OTHOS_ACCESS_COOKIE`
- `OTHOS_ACCESS_TOKEN`
- `othos_auth_set_cookie`
- `othos_auth_login`
- `othos_auth_login_with_personal_token`

For new setups, prefer `othos_auth_connect` or `OTHOS_PERSONAL_TOKEN`.

## Example Prompts

Once connected, your agent can handle prompts like:

- `Check my Othos authentication status.`
- `List my organizations and tell me which one is active.`
- `Switch to organization 8f2d...`
- `Show me the projects in my current organization.`
- `Create a project called Website Redesign.`
- `List the columns for project 2c6a...`
- `Create a high-priority ticket called Fix OAuth redirect in column 91d4...`
- `Move ticket 4a7f... to column c12e...`
- `Show ticket 77b2... using the template format.`

## MCP Tools

The server currently exposes the following tool groups.

### Authentication

- `othos_auth_status` checks whether the server currently has valid auth configured.
- `othos_auth_connect` starts browser-based authorization and stores the returned bearer token.
- `othos_auth_set_cookie` sets auth manually using a cookie or raw access token.
- `othos_auth_set_personal_token` sets a bearer token and can persist it locally.
- `othos_auth_login_with_personal_token` validates and stores a bearer token for API use.
- `othos_auth_login` signs in with email and password.
- `othos_auth_logout` clears the current auth session.
- `othos_auth_create_personal_token` currently returns a compatibility error because the legacy API endpoint is gone.
- `othos_auth_revoke_personal_token` currently returns a compatibility error because the legacy API endpoint is gone.

### Organizations

- `othos_organization_list` lists organizations available to the authenticated user.
- `othos_organization_current` returns the current active organization.
- `othos_organization_change` switches the active organization context.

### Projects

- `othos_project_list`
- `othos_project_get`
- `othos_project_create`
- `othos_project_update`
- `othos_project_delete`
- `othos_project_members`
- `othos_project_assign_member`
- `othos_project_unassign_member`

### Columns

- `othos_column_list`
- `othos_column_create`
- `othos_column_update`
- `othos_column_delete`

### Tickets

- `othos_ticket_list_by_column`
- `othos_ticket_list_by_column_template`
- `othos_ticket_get`
- `othos_ticket_get_template`
- `othos_ticket_create`
- `othos_ticket_update`
- `othos_ticket_move`
- `othos_ticket_delete`
- `othos_ticket_assign_member`
- `othos_ticket_unassign_member`

> [!TIP]
> The `*_template` ticket tools return a fixed, chat-friendly text format that is useful when you want consistent summaries instead of raw JSON.

## HTTP Transport with OAuth

Besides local `stdio` mode, the package can run as a Streamable HTTP MCP server protected by OAuth bearer tokens.

Start the server in HTTP mode:

```bash
OTHOS_MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_PORT=8787 \
node dist/index.js --http
```

In HTTP mode:

- clients connect to `http://127.0.0.1:8787/mcp`
- bearer authentication is required on the MCP transport
- tokens are validated through the Othos introspection endpoint
- the local `othos_auth_*` helper tools are disabled because auth is handled by the MCP OAuth flow
- the server requires the `mcp:tools` scope

For the published remote server at `https://mcp.othos.com.br/mcp`, a fresh
unauthenticated client should expect the transport to reject the connection
until it provides a valid bearer token. This is expected behavior.

Example unauthenticated remote behavior:

```json
{
  "error": "invalid_token",
  "error_description": "Missing Authorization header"
}
```

## Environment Variables

### API and auth

- `OTHOS_API_URL`: Othos API base URL. Defaults to `https://api.othos.com.br/api/v1`.
- `NEXT_PUBLIC_API_URL`: fallback API base URL when `OTHOS_API_URL` is not set.
- `OTHOS_PERSONAL_TOKEN`: Othos bearer token used as API auth.
- `OTHOS_PERSONAL_TOKEN_PATH`: absolute path used to load or persist a bearer token. If unset, local stdio mode falls back to `$XDG_CONFIG_HOME/othos-mcp/personal-token` or `$HOME/.config/othos-mcp/personal-token`.
- `OTHOS_ACCESS_COOKIE`: existing Othos cookie header for compatibility mode.
- `OTHOS_ACCESS_TOKEN`: existing access token. Non-PAT values are treated as cookie auth.

### HTTP transport

- `OTHOS_MCP_TRANSPORT`: set to `http` to enable Streamable HTTP mode.
- `MCP_HOST`: HTTP bind host. Defaults to `127.0.0.1`.
- `MCP_PORT`: HTTP bind port. Defaults to `8787`.
- `OTHOS_OAUTH_RESOURCE_METADATA_URL`: OAuth protected resource metadata URL.
- `OTHOS_OAUTH_INTROSPECTION_URL`: OAuth token introspection URL.

## Local Development

Clone the repository and run:

```bash
pnpm install
pnpm build
pnpm typecheck
pnpm start
```

For development builds:

```bash
pnpm dev
```

## Repository

- package name: `@othos-io/othos-mcp`
- source: [othos-io/othos-mcp-server](https://github.com/othos-io/othos-mcp-server)