MCP server

Connect any Model Context Protocol client to Oceanir. Geolocate images directly from a Claude Code, Claude Desktop, Cursor, Cline, or Windsurf conversation. Auth via OAuth, billed via the same credits as the web app and REST API.

Endpoint

https://mcp.oceanir.ai

Transport: Streamable HTTP. Authentication: OAuth 2.1 bearer token (issued by Oceanir, no API key needed).

Install

Pick your MCP client. First tool call after install opens a browser to sign you in and confirm your paid Oceanir subscription.

Claude Code (CLI)

claude mcp add oceanir https://mcp.oceanir.ai

Single command. Browser opens for OAuth on first tool call.

Claude Desktop

{
  "mcpServers": {
    "oceanir": {
      "type": "http",
      "url": "https://mcp.oceanir.ai"
    }
  }
}

Add to claude_desktop_config.json under mcpServers. Restart Claude Desktop.

Cursor

{
  "mcpServers": {
    "oceanir": {
      "url": "https://mcp.oceanir.ai"
    }
  }
}

Settings → MCP → add custom server. Cursor handles OAuth automatically.

Authentication flow

01Your MCP client makes a first request to /api/mcp without a token.
02Server responds 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp.
03Client discovers the OAuth issuer (oceanir.ai/api/auth/oauth) and registers itself automatically (RFC 7591 dynamic client registration).
04Client opens your browser to oceanir.ai/auth, you sign in (or sign up).
05If you don't have a paid subscription, you're redirected to /pricing. After checkout you land back on the consent screen.
06Consent screen shows the requested mcp:tools permission. Grant it. The client receives a bearer token.
07All subsequent tool calls use that token. It refreshes automatically.

Claude Code /locate skill

For Claude Code, Oceanir also ships a /locateskill on top of the MCP server. The skill chooses D1, D2, or D3 based on the user's intent, checks credits when needed, and keeps expensive forensic calls behind clear user intent.

Install MCP + skill

claude mcp add oceanir https://mcp.oceanir.ai
/plugin marketplace add oceanir-ai/claude-plugins
/plugin install locate@oceanir

Once installed, ask Claude Code to locate or verify an image. The MCP server remains the authenticated transport; the skill is the workflow layer.

Tools exposed

geolocate_image

Analyze an image and return its probable real-world location.

Arguments

image_urlstring (URL)Either / orPublic HTTPS URL to the image.

image_b64string (base64)Either / orBase64-encoded image bytes. No data: prefix.

depth1 | 2 | 3optionalSurface (1cr) / Standard (3cr) / Forensic (10cr). Default 1.

Returns: Ranked location candidates, confidence score, and the visual evidence chain. Precision fields such as radius are included when available.

check_credits

Return the authenticated account's remaining credits and monthly allowance.

Returns: JSON balance object: { remaining, monthly_allowance, plan }.

Billing

MCP usage burns the same credits as the web app and REST API. There is no separate metered billing. See the API reference for the credit cost per action, or the pricing page for plan tiers and rate limits.

Subscription required

MCP access requires an active Pro, Unit, or Enterprise subscription. The OAuth consent step blocks free accounts and prompts upgrade. You can cancel anytime from Settings → Billing.

Troubleshooting

Browser doesn't open on first call: Some headless agents (CI, sandboxed environments) cannot launch a browser. Use the npm @oceanir/mcp package with an API key instead.
402 Payment Required after subscribing: Stripe webhook may not have updated your tier yet. Wait 30 seconds and re-run the tool, or check your subscription at Settings → Billing.
Token revoked: Tokens are revoked when you cancel or downgrade. Resubscribe and re-run the install command to mint a new token.