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

# MCP server

> Connect Claude and other MCP clients to Pharus: the address, signing in with OAuth, the tools, scopes and limits.

> [!NOTE]
>
> **Plans:** Every plan and the free trial. **Who:** any member can connect an agent once an owner or admin has [allowed agents](https://docs.pharussecurity.com/incidents/agents.md#allow-agents-in-your-workspace). Owners and admins create read tokens.

The Pharus MCP server lets an AI agent work with your workspace over the [Model Context Protocol](https://modelcontextprotocol.io). It reads your data and, when a person connects it with OAuth, registers vulnerabilities and drafts reports for that person to review. It can't file, approve or send. See [work with an agent](https://docs.pharussecurity.com/incidents/agents.md) for what that means day to day.

The address is `https://mcp.pharussecurity.com/mcp` (Streamable HTTP).

## Connect a client

Clients that support OAuth sign you in by themselves: add the address, and your browser opens Pharus. You choose the workspace and what the agent may do.

> [tab] Claude and Claude Desktop
>
> Add `https://mcp.pharussecurity.com/mcp` as a custom connector, then select **Connect**.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http pharus https://mcp.pharussecurity.com/mcp
> ```

> [tab] Cursor
>
> In `~/.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "pharus": { "url": "https://mcp.pharussecurity.com/mcp" }
>   }
> }
> ```

> [tab] VS Code
>
> In `.vscode/mcp.json`:
>
> ```json theme={null}
> {
>   "servers": {
>     "pharus": { "type": "http", "url": "https://mcp.pharussecurity.com/mcp" }
>   }
> }
> ```

### With a read token

A client that can't sign in can read with a [read token](https://docs.pharussecurity.com/api-reference/introduction.md#create-a-token) instead, by sending `Authorization: Bearer phr_...`. A read token gets the read tools only, on every plan.

Writing always needs a person's OAuth connection, so that every action names someone. That means an agent can't write on a schedule with nobody behind it.

## Tools

### Read

| Tool | What it returns |
| - | - |
| `list_deadlines` | Every deadline, nearest first: reports due, assessments to do, fix deadlines |
| `list_vulnerabilities`, `get_vulnerability` | Vulnerabilities per component and product family, and one with every match |
| `list_incidents`, `get_incident` | Open or closed incidents, and one with its clocks, decision and filings. Never draft text. |
| `list_product_families` | The active product families and their ids |
| `list_events` | The audit trail, newest first |
| `list_sboms`, `get_sbom` | SBOMs and their components |
| `list_security_advisories`, `get_security_advisory` | Security advisories and their CSAF documents |

### Register and draft

These need a connection given `incidents:draft`. See the [HTTP endpoints](https://docs.pharussecurity.com/api-reference/agent-api.md) behind them.

| Tool | What it does |
| - | - |
| `register_vulnerability` | Opens one incident per product family, being assessed. No clock starts. |
| `link_product_family` | Adds a family to a registered vulnerability: its own incident, being assessed |
| `get_report_pack` | A CRA report's fields as they stand, what's missing, what an agent may write, and what became of its latest proposal |
| `draft_report` | Proposes text for a CRA report. It stays out of the pack until a person accepts it. |

No tool starts a clock, records or approves a decision, marks a report as submitted, sets a VEX status, closes an incident, publishes an advisory or sends anything.

## Scopes

| Scope | Lets the agent | Tokens |
| - | - | - |
| `workspace:read` | Use the read tools | OAuth and read tokens |
| `incidents:draft` | Use the register and draft tools | OAuth only |
| `offline_access` | Stay connected without you signing in again | OAuth only |

You choose at sign-in. To change what an agent may do, disconnect it and connect it again.

On every request Pharus checks the token, that its person is still a confirmed member of the workspace (with two-step verification where required), that the workspace allows agents, and for a write that the workspace isn't read-only. What the agent may do follows from that person's rights, read at the time, never from when it connected.

## Tokens

* **Access tokens** start with `pho_` and last 1 hour. **Refresh tokens** start with `phor_` and last 30 days. Each refresh replaces the refresh token, and using an old one ends them all for that agent and person.
* Tokens are issued for this server alone, and belong to one person in one workspace.
* Pharus stores only a hash of each.
* Signing out ends the access token, and the client gets a new one with its refresh token. A password reset disconnects the agent.

For client authors: Pharus publishes protected resource metadata at `https://mcp.pharussecurity.com/.well-known/oauth-protected-resource/mcp` and authorization server metadata at `https://app.pharussecurity.com/.well-known/oauth-authorization-server/api/auth`. Clients register with a Client ID Metadata Document or dynamically, with all their redirect URIs on one host. PKCE with `S256` is required, and clients must send `resource`. Only public clients and the authorization code and refresh token grants are offered to agents.

## Limits

| What | Limit |
| - | - |
| Reads | 600 per hour per connection or read token |
| Writes | 60 per hour per connection |
| New incidents from agents | 20 per workspace in 24 hours |

## Errors

The agent gets a tool error it can read and pass on. If its connection has ended, the client gets `401` and asks you to sign in again. If the workspace doesn't allow agents, it gets `403`.

## Related

> [card] [Work with an agent](https://docs.pharussecurity.com/incidents/agents.md)

> [card] [Register and draft](https://docs.pharussecurity.com/api-reference/agent-api.md)

> [card] [Read workspace data](https://docs.pharussecurity.com/api-reference/read-api.md)

> [card] [Audit trail](https://docs.pharussecurity.com/reports/audit-trail.md)


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