GuideClaude DesktopChatGPT

Using Orca with Claude & ChatGPT

Orca 2 can be connected to AI assistants so they can geolocate images on your behalf — no manual upload required. You describe a photo, paste a URL, or share an image and the assistant automatically calls Orca to find where it was taken.

Claude Desktop (MCP)

Claude Desktop supports the Model Context Protocol (MCP), which lets you give Claude access to external tools. Adding Orca as an MCP tool means Claude can call locate_image directly during any conversation.

1. Get your Orca API key

Go to Workspace → API Keys and create a new key. Copy it — you will need it in the next step.

2. Create the MCP server file

Save the following as ~/orca-mcp/index.js on your machine:

#!/usr/bin/env node
// Orca MCP server for Claude Desktop
// Requires: npm install @modelcontextprotocol/sdk node-fetch

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fetch from "node-fetch";

const ORCA_API = "https://oceanir.ai/api";
const API_KEY  = process.env.ORCA_API_KEY;

const server = new Server(
  { name: "orca", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "locate_image",
      description: "Geolocate an image using Orca 2. Returns the location, coordinates, confidence score, and reasoning.",
      inputSchema: {
        type: "object",
        properties: {
          image_url: { type: "string", description: "Public URL of the image to analyze" },
          depth: {
            type: "string",
            enum: ["d1", "d2", "d3"],
            description: "d1=quick (15s), d2=standard (35s), d3=deep (60s). Default: d2"
          }
        },
        required: ["image_url"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (req) => {
  const { image_url, depth = "d2" } = req.params.arguments;

  const imgRes = await fetch(image_url);
  const blob   = await imgRes.buffer();

  const form = new FormData();
  form.append("image", new Blob([blob]), "image.jpg");
  form.append("depth", depth);

  const res  = await fetch(`${ORCA_API}/workspace/analyze`, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
    body: form,
  });
  const data = await res.json();
  const a    = data.analysis;

  return {
    content: [{
      type: "text",
      text: [
        `Location: ${a.location}`,
        `Coordinates: ${a.coordinates}`,
        `Confidence: ${a.confidence}%`,
        `Model: ${a.aiModel}`,
        `Depth: ${(a.depth || depth).toUpperCase()}`,
        `\nReasoning: ${a.reasoning}`,
      ].join("\n")
    }]
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);

3. Install dependencies

cd ~/orca-mcp
npm install @modelcontextprotocol/sdk node-fetch

4. Configure Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "orca": {
      "command": "node",
      "args": ["/home/nextjs/orca-mcp/index.js"],
      "env": {
        "ORCA_API_KEY": "your-api-key-here"
      }
    }
  }
}

5. Restart Claude Desktop

Quit and relaunch Claude Desktop. You will see a hammer icon in the input bar indicating tools are available. Claude can now geolocate any image you share or link to.

Try it: Paste an image URL in Claude and ask "Where was this taken?" — Claude will automatically call Orca and return the location with reasoning.

ChatGPT (Custom GPT Action)

ChatGPT Custom GPTs support Actions — HTTP endpoints described by an OpenAPI schema. You can create a GPT that calls Orca whenever it needs to geolocate an image.

1. Create a Custom GPT

Go to chatgpt.com → Explore GPTs → Create. Give it a name like Orca Geolocator and a description. In the system prompt, add:

You are a geolocation assistant powered by Orca 2 by Oceanir.
When the user shares an image URL or asks where a photo was taken,
call the locate_image action and present the location, coordinates,
confidence score, and reasoning in a clear format.

2. Add the Action

In the GPT editor, click Add actions and paste this OpenAPI schema:

openapi: 3.1.0
info:
  title: Orca Geolocation API
  version: 1.0.0
servers:
  - url: https://oceanir.ai
paths:
  /api/workspace/analyze:
    post:
      operationId: locate_image
      summary: Geolocate an image using Orca 2
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [image_url]
              properties:
                image_url:
                  type: string
                  description: Public URL of the image
                depth:
                  type: string
                  enum: [d1, d2, d3]
                  default: d2
                  description: "d1=quick, d2=standard, d3=deep"
      responses:
        "200":
          description: Geolocation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  analysis:
                    type: object
                    properties:
                      location:    { type: string }
                      coordinates: { type: string }
                      confidence:  { type: number }
                      reasoning:   { type: string }
                      aiModel:     { type: string }
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

3. Set authentication

In the Action settings, choose API Key authentication, set the header name to Authorization, and enter Bearer your-api-key-here as the value.

4. Publish and use

Save the GPT. Share the image URL in the chat and ask where it was taken — your GPT will call Orca and return the result.

Note: ChatGPT Actions can only call image URLs, not upload binary files directly. Make sure the image is publicly accessible before passing it to the GPT.

Credit usage

Each call to Orca from Claude or ChatGPT draws from your Oceanir balance. D1 (Surface) is free for signed-in accounts. D2 (Standard) uses 3 credits per call. D3 (OSINT, full forensic) is exclusive to Investigator and Unit subscribers — it's not purchasable with credit packs. Monitor usage in your Workspace → Usage dashboard.