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

# Hosted MCP

> Connect the hosted Shoal MCP server from Claude and other MCP clients

Shoal provides a hosted [Model Context Protocol](https://modelcontextprotocol.io) server at `https://api.shoal.xyz/mcp`. This is the recommended way to use Shoal inside Claude, Cursor, Windsurf, Cline, and other MCP-compatible agents.

Unlike the older local `shoal-mcp` binary flow, the hosted server uses Shoal app authentication. Users sign in at `app.shoal.xyz`, approve access, and Shoal issues short-lived MCP tokens without exposing the raw API key to the agent client.

## Hosted MCP (Recommended)

### Server URL

```text theme={null}
https://api.shoal.xyz/mcp
```

### OAuth discovery

```text theme={null}
https://api.shoal.xyz/.well-known/oauth-authorization-server
https://api.shoal.xyz/.well-known/oauth-protected-resource/mcp
```

## Setup

**Step 1** — Add Shoal as an MCP server in your agent using the server URL above.

For clients that support hosted/remote MCP directly, use:

* **Server URL:** `https://api.shoal.xyz/mcp`
* **Name:** `shoal` (or any name you prefer)

**Step 2** — Start authentication from the client.

Shoal will open the browser and redirect you to `app.shoal.xyz`.

**Step 3** — Sign in to Shoal and approve access.

Shoal checks that the signed-in account already has a valid API key with remaining quota, then completes the MCP OAuth flow.

## Claude Setup

### Claude Web (Pro and Max)

1. Open Claude and go to `Settings > Connectors`.
2. In the Connectors section, click `Add custom connector`.
3. Enter a connector name such as `Shoal`.
4. Paste the connector URL:

```text theme={null}
https://api.shoal.xyz/mcp
```

5. Click `Add`.
6. Click `Connect` for the new Shoal connector.
7. Claude opens the browser and sends you to `app.shoal.xyz`.
8. Sign in to Shoal if needed, then approve access.
9. Return to Claude.
10. In the chat composer, open `Search and tools` and enable the Shoal connector or the specific Shoal tools you want to use.

### Claude for Work (Team and Enterprise)

Owners or Primary Owners must first add the connector for the workspace:

1. Open Claude and go to `Settings > Connectors`.
2. Switch to `Organization connectors`.
3. Click `Add custom connector`.
4. Name it `Shoal`.
5. Paste:

```text theme={null}
https://api.shoal.xyz/mcp
```

6. Click `Add`.

After that, each user connects individually:

1. Open `Search and tools` in Claude.
2. Find Shoal and click `Connect`.
3. Sign in to Shoal in the browser and approve access.
4. Return to Claude and enable the Shoal tools you want to use.

### Claude Code

For Claude Code, the easiest setup path is the Shoal plugin marketplace. It bundles:

* the hosted Shoal MCP server
* the Shoal skill
* app-based OAuth to `https://api.shoal.xyz/mcp`

1. Open Claude Code.
2. Add the Shoal marketplace:

```text theme={null}
/plugin marketplace add shoalresearch/shoal-skill
```

3. Install the Shoal plugin:

```text theme={null}
/plugin install shoal@shoalresearch-tools
```

4. Reload plugins:

```text theme={null}
/reload-plugins
```

5. Open the plugin or MCP connection flow when prompted.
6. Claude Code opens the browser and sends you to `app.shoal.xyz`.
7. Sign in to Shoal if needed, then approve access.
8. Return to Claude Code and use the installed Shoal tools.

## Claude Notes

* Remote MCP connectors are supported in Claude Web and Claude Desktop.
* Claude Code can use the same hosted Shoal MCP server through the Shoal plugin marketplace.
* Claude mobile can use connectors that were already added through `claude.ai`, but new remote connectors are typically added from the web or desktop app first.
* If you do not see `Connectors`, make sure your Claude plan supports remote MCP connectors.

## Important

* Users must already have a Shoal API key on their account.
* That API key must still have quota remaining.
* MCP usage is tracked against the same Shoal API key allocation as normal API usage.
* The MCP client never needs the raw Shoal API key directly.

## What the hosted MCP exposes

The hosted Shoal MCP exposes the Shoal API surfaces that are available to the authenticated account's current plan. The exact tool list is determined after authentication.

Common tool categories include:

* Entity resolution by name or alias
* Entity detail, relationships, and references
* Timeline and search across signal and radar events
* Top signals
* Signal and radar lookups by entity or category
* Categories
* Usage stats

Higher-tier accounts may also see:

* Briefs and batch briefs
* Bulk feed or webhook tools, when enabled on the plan

Example prompts:

```text theme={null}
Resolve Ethereum to a Shoal entity, show its relationships, then summarize its timeline from the last 7 days.
```

```text theme={null}
Get the top Shoal signals from the last 2 hours.
```

```text theme={null}
Search for Ethereum Foundation and give me the broader cross-entity context.
```

```text theme={null}
Show my current Shoal usage and quota.
```

## Legacy Local MCP Fallback

If your client does not support hosted MCP yet, you can still run the older local stdio server.

**Step 1** — Install the CLI and authenticate:

```bash theme={null}
npm install -g shoal-cli
shoal auth YOUR_API_KEY
```

**Step 2** — Register the local stdio MCP server:

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport stdio shoal -- shoal-mcp
    ```

    Or add manually to `~/.claude/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "shoal": {
          "command": "shoal-mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "shoal": {
          "command": "shoal-mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf / Cline">
    Add to your MCP settings file:

    ```json theme={null}
    {
      "mcpServers": {
        "shoal": {
          "command": "shoal-mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

This fallback uses a locally stored Shoal API key. Prefer the hosted MCP flow whenever the client supports it.