Othos MCP

@othos-io/othos-mcp is a Model Context Protocol (MCP) server for the Othos Platform. 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:

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:

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

Codex CLI

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:

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:

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:

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:

{
  "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:

pnpm install
pnpm build
pnpm typecheck
pnpm start

For development builds:

pnpm dev

Repository

• package name: @othos-io/othos-mcp
• source: othos-io/othos-mcp-server