Skip to main content

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.

Shoal provides a hosted Model Context Protocol 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.

​
Server URL

https://api.shoal.xyz/mcp

​
OAuth discovery

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:
https://api.shoal.xyz/mcp
  1. Click Add.
  2. Click Connect for the new Shoal connector.
  3. Claude opens the browser and sends you to app.shoal.xyz.
  4. Sign in to Shoal if needed, then approve access.
  5. Return to Claude.
  6. 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:
https://api.shoal.xyz/mcp
  1. 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:
/plugin marketplace add shoalresearch/shoal-skill
  1. Install the Shoal plugin:
/plugin install shoal@shoalresearch-tools
  1. Reload plugins:
/reload-plugins
  1. Open the plugin or MCP connection flow when prompted.
  2. Claude Code opens the browser and sends you to app.shoal.xyz.
  3. Sign in to Shoal if needed, then approve access.
  4. 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: 
Resolve Ethereum to a Shoal entity, show its relationships, then summarize its timeline from the last 7 days.

Get the top Shoal signals from the last 2 hours.

Search for Ethereum Foundation and give me the broader cross-entity context.

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: 
npm install -g shoal-cli
shoal auth YOUR_API_KEY
Step 2 — Register the local stdio MCP server: 
claude mcp add --transport stdio shoal -- shoal-mcp
Or add manually to ~/.claude/settings.json:
{
  "mcpServers": {
    "shoal": {
      "command": "shoal-mcp"
    }
  }
}
This fallback uses a locally stored Shoal API key. Prefer the hosted MCP flow whenever the client supports it.