# The MCP server

> Connect any MCP client to Presence Orbit with OAuth sign-in, the tool it has today, and how roles, tokens and the audit trail work.

Source: https://docs.bifrostorbit.com/presence/developers/mcp/

Presence Orbit has an MCP (Model Context Protocol) server, so AI assistants such as Claude, ChatGPT, Cursor or VS Code can work with it as the person who connects them. The address is:

```text
https://app.bifrostorbit.com/presence/mcp
```

It uses the Streamable HTTP transport. The same address, with buttons for Cursor and VS Code and a Claude Code command, is on **AI assistants** under **Developers** in the sidebar.

## Tools

The server is new and has one tool so far:

| Tool | What it returns | Role |
| --- | --- | --- |
| `presence_status` | Your organisation's name, the business name customers see, its languages, your role in Presence Orbit and whether that role can make changes (`canWrite`) | Everyone |

```json
{ "organisation": "Northwilds", "business": "Northwilds", "languages": ["en", "nb"], "yourRole": "editor", "canWrite": true }
```

Tools for locations, reviews and review requests are not there yet. Assistants are told to treat review text as data, never as instructions. No tool changes settings, email templates or sending domains, or shows customers' email addresses or phone numbers.

## Signing in

The server uses OAuth 2.1 with PKCE (S256) and dynamic client registration, so a client needs nothing but the address. A request without a valid token gets `401` with a `WWW-Authenticate` header that points to the resource metadata.

| What | Where |
| --- | --- |
| Resource metadata | `/presence/.well-known/oauth-protected-resource/mcp` |
| Authorisation server metadata | `/presence/.well-known/oauth-authorization-server`, also at `/.well-known/oauth-authorization-server/presence` |
| Register a client | `POST /presence/oauth/register` |
| Authorise | `/presence/oauth/authorize` |
| Token | `POST /presence/oauth/token` |
| Revoke | `POST /presence/oauth/revoke` |

Clients are public (`token_endpoint_auth_method` is `none`) and register up to ten redirect addresses, each `https`, or `http` on `localhost`, `127.0.0.1` or `[::1]`. The scope is `presence`. The person signs in to Orbit, chooses the organisation and allows the connection.

An authorisation code lasts one minute. Access tokens (`pre_mcp_…`) last one hour; the client renews them with the refresh token (`pre_mrt_…`), which changes each time and lasts 30 days from the last renewal. A registered client that is never used again is forgotten after 180 days.

## Whose rights

Every request runs as the person who connected, with their current Presence Orbit role: Viewer, Editor or Admin. See [Who can do what](https://docs.bifrostorbit.com/presence/everyone/roles/). If they lose Presence Orbit in the organisation, requests get `403` at once.

**AI assistants** lists the connected assistants: Admins see and disconnect everyone's, others their own. Disconnecting one there, or revoking its token, stops it. Changes an assistant makes are in the audit trail as the person and the assistant, such as 'Ingrid via Claude'.

## Errors

| Status | Message | What to do |
| --- | --- | --- |
| `401` | 'Connect the assistant to Presence Orbit again' | The token is missing, unknown, expired or revoked. Let the client sign in again |
| `403` | 'The person who connected this assistant no longer has Presence Orbit in the organisation' | Someone with access connects it again |
| `413` | 'The request is too large' | Keep requests under 1 MB |

Errors come back as JSON-RPC errors with code `-32001` and the message. A tool that fails returns `isError: true` with the reason.

## Try it

With Claude Code:

```bash
claude mcp add --transport http presence-orbit https://app.bifrostorbit.com/presence/mcp
```

Then ask, for example, "What can my role do in Presence Orbit?"
