> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocean.security/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server Overview
> Connect AI agents to Ocean Security over the Model Context Protocol (MCP) to query threats, metrics, phishing reports, and allow/deny lists in natural language.
The Ocean MCP server is in **beta**. It's rolling out gradually and the tool set may change.
If you don't see Ocean's tools after connecting, MCP access may not be enabled for your
tenant yet — contact Ocean support.
## Overview
Ocean exposes a **Model Context Protocol (MCP)** server so you can bring your Ocean
security data directly into AI agents like Claude Code, GitHub Copilot, and Cursor. Once
connected, you can ask questions in natural language — "how many threats did we block last
week?", "show me the latest phishing reports", "is this domain on our deny list?" — and the
agent calls Ocean on your behalf.
The MCP server is backed by the same [Ocean Security API](/api-reference/introduction) and
enforces the same per-tenant permissions, so an agent can only see and do what the connected
identity is allowed to.
## Connection details
The Ocean MCP server is a **remote server** that speaks MCP over **streamable HTTP**. Point
any MCP-capable client at the endpoint below.
| Setting | Value |
| ------------------ | ------------------------------------------------ |
| **Endpoint** | `https://api.ocean.security/mcp` |
| **Transport** | Streamable HTTP (`http`) |
| **Authentication** | OAuth 2.1 (recommended) or an `X-Api-Key` header |
## Prerequisites
* **MCP access enabled for your tenant.** MCP is being rolled out gradually. If you connect
successfully but see no Ocean tools, MCP access may not be enabled for your tenant yet —
contact Ocean support to turn it on.
* **An MCP-capable client.** See the per-client guides below.
* **Either an Ocean account or an Ocean API key**, depending on which authentication method
you use — see below.
## Authentication
Ocean supports two ways to authenticate an MCP client. **OAuth is the recommended
method**; an API key remains available for cases OAuth doesn't fit.
Sign in with your Ocean account. No credential to copy, store, or rotate; access follows
your own role. Read-only.
Send an `X-Api-Key` header. Best for headless and CI use, and required for the
allow/deny **write** tools.
### OAuth 2.1 (recommended)
Point your client at `https://api.ocean.security/mcp` with **no credential at all** and let it
run the OAuth flow. See the per-client guides below for the exact configuration.
Your client discovers Ocean's authorization server, registers itself, and opens a browser
window where you sign in with your Ocean account and approve the access it asked for. From then
on the client holds a short-lived token and refreshes it on its own — you won't be asked again
until the grant expires or is revoked.
Why it's preferred:
* **Nothing to store or leak.** No long-lived secret in a config file, an environment
variable, or a shared repository.
* **Your identity, your access.** Tools are granted from your own Ocean role rather than from
a shared key, and the tenant comes from your account.
* **Short-lived tokens.** The client refreshes automatically; revoking your Ocean access
revokes the agent's.
Every client that supports remote MCP servers with OAuth handles this the same way — there is
no client ID or client secret to configure.
**The OAuth surface is read-only.** A token issued through OAuth can never modify Ocean
data, whatever it consented to. The allow/deny write tools (`create_allow_deny_entry`,
`update_allow_deny_entry`, `delete_allow_deny_entry`) are only reachable with an API key.
#### Scopes
During consent you approve one or more scopes. Each maps to the tools it unlocks:
| Scope | Unlocks |
| ---------------------- | --------------------------------------------------------------------------- |
| `threats:read` | `list_threats`, `get_threat` |
| `metrics:read` | `get_threat_metrics_summary` |
| `sonar:read` | `list_phishing_reports`, `get_phishing_report`, `get_phishing_report_stats` |
| `settings:read` | `list_allow_deny_entries` |
| `decision_center:read` | `query_decision_center` |
Which scopes you may approve depends on your Ocean role — the Admin and Analyst roles
(including their read-only variants) can approve all five. Scopes your role doesn't permit
are removed before the consent screen, and a partial grant works fine: the agent simply sees
fewer tools.
### API key (alternative)
Send your Ocean API key in the `X-Api-Key` header. It's the same key as the
[REST API](/api-reference/introduction#authentication) — there is no separate MCP credential.
Use an API key when:
* You need the allow/deny **write** tools, which OAuth cannot reach.
* The client runs unattended (CI, a server, a container) and no one can complete a browser
sign-in.
* Your MCP client doesn't support OAuth for remote servers.
Treat your API key like a password. Store it in your client's secret input or an environment
variable rather than committing it to a shared config file, and never expose it in
client-side code or public repositories.
## Set up your agent
Ocean is listed in Anthropic's connectors directory — add it to Claude in one click, no
endpoint or credential to enter.
Add Ocean to Claude Code via the CLI or an `.mcp.json` file.
Add Ocean to Copilot agent mode in VS Code.
Add Ocean to Cursor globally or per project.
### Claude connectors directory
Ocean is published in [Anthropic's connectors
directory](https://claude.ai/directory/connectors/ocean), so Claude users don't have to add
the server by hand. From the directory page — or from **Settings → Connectors** in Claude —
choose **Connect**, sign in with your Ocean account, and approve the access Claude asks for.
The directory listing connects over OAuth, so it's subject to the same read-only limit as any
other OAuth client: the allow/deny write tools stay unreachable. Use an API key in a client
that supports headers if you need them.
## Available tools
Once connected, the agent discovers Ocean's tools automatically. Discovery is
permission-aware — a client only sees the tools the connected identity is allowed to call.
### Threats
| Tool | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `list_threats` | List recently detected email threats within a look-back window. |
| `get_threat` | Full detail for a threat — including its indicators — by its `id` or by the email's `internet_message_id`. |
### Metrics
| Tool | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_threat_metrics_summary` | Threat metrics for a window in one call: ROI figures, daily volume, top threat types, most-targeted users, highlighted threats. Request a subset with `sections`. |
### AI Response (phishing reports)
| Tool | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `list_phishing_reports` | List user-reported phishing reports within a look-back window. |
| `get_phishing_report` | Full detail for one report — analysis reasoning and content links — by its `id`, or every report matching an `internet_message_id`. |
| `get_phishing_report_stats` | Report counts per verdict plus mean time to resolution. |
### Settings (allow/deny list)
| Tool | Description |
| ------------------------- | -------------------------------------------------------------- |
| `list_allow_deny_entries` | List allow or deny entries, optionally filtered by identifier. |
| `create_allow_deny_entry` | Add an allow or deny entry. **API key only.** |
| `update_allow_deny_entry` | Update an existing entry. **API key only.** |
| `delete_allow_deny_entry` | Remove an entry. **API key only.** |
The exact set of tools an agent sees depends on how it authenticated, the permissions behind
that identity, and your tenant's configuration. An OAuth client never sees the write tools;
a read-only API key doesn't either.
## Troubleshooting
* **No Ocean tools appear.** Confirm the endpoint is `https://api.ocean.security/mcp`, that
the client is authenticated (signed in, or sending `X-Api-Key`), and that MCP access is
enabled for your tenant.
* **Authentication errors (401) with OAuth.** The token expired and the client should refresh
it automatically. If the prompt to sign in keeps returning, remove and re-add the server so
the client re-runs the flow from scratch.
* **Sign-in or consent fails.** Your Ocean account needs an active tenant and a role that
permits MCP access. If you have access to more than one Ocean tenant, contact Ocean support.
* **Authentication errors (401) with an API key.** Your API key is missing, expired, or
inactive. Generate a fresh key and update your client config.
* **The allow/deny write tools are missing.** They're unreachable over OAuth by design. Switch
that client to an API key with the allow/deny edit permission.
* **Other tools are missing.** Tool discovery is permission-aware. A tool you expect to see is
hidden if your identity lacks its permission or the feature is disabled for your tenant.