MCP overview

Orsane ships a hosted Model Context Protocol server so AI clients like Claude Desktop, Claude Code, and Cursor can read and edit tasks in your team on your behalf. The server runs alongside the REST API and authenticates each session with OAuth 2.1 — no API key to copy around.

Endpoint

https://api.orsane.app/mcp

The server speaks the Streamable HTTP transport in stateless mode: every JSON-RPC call is a single HTTP request, so you can point any MCP client at the URL above with no extra setup.

Authentication

Unlike the REST API, the MCP server does not use API keys. Clients authenticate with OAuth 2.1 bearer tokens, and Orsane publishes the standard discovery metadata:

URL	Purpose
https://api.orsane.app/.well-known/oauth-protected-resource	Resource metadata advertised on 401.
https://api.orsane.app/.well-known/oauth-authorization-server	Authorization server metadata.

When a client first hits /mcp without a token, Orsane responds 401 with a WWW-Authenticate: Bearer resource_metadata="…" header. Compliant MCP clients follow that link, perform the OAuth dance against the authorization server, and retry the request with a bearer token.

During the OAuth flow, Orsane shows a consent screen where you pick which team the bearer token should be scoped to. That choice sticks for the lifetime of the token (and any refresh tokens issued from it) — to switch teams, revoke the connection in your client and re-authorize.

Adding to Claude Desktop / Claude Code

Most MCP clients accept the URL directly. In Claude Desktop or Claude Code, add a new MCP server with the URL https://api.orsane.app/mcp — the client will open a browser window to complete the OAuth login on first use.

Tools

The server exposes the following tools. Each one runs scoped to the authenticated user’s team.

Name	Description
search_tasks	Search tasks the user has access to.
create_task	Create a task, optionally on lists or as a subtask.
get_task	Get a task by id with full detail.
update_task	Update a task’s title, status, priority, due date, or assignees.
list_task_lists	List task lists the user belongs to.
create_task_list	Create a task list; the caller is granted access automatically.
list_task_statuses	List task statuses configured in the user’s team.
list_users	List users in the user’s team.

Conventions

A few things that hold across every tool:

• Scoping. Every call is scoped to the OAuth user’s team. You’ll never see data from a team the user isn’t a member of.
• IDs. Task and list IDs are integers; user and team IDs are strings (UUIDs).
• Timestamps. ISO 8601 UTC strings (2026-05-08T12:34:56.000Z).
• Errors. Tool errors come back as a normal MCP tool result with isError: true and a single text content block describing the failure.
• Realtime. Edits made through MCP fan out over the same realtime channel the web app uses, so connected clients see the changes without a refresh.