MCP Server

The Raa Labs MCP server exposes your fleet's time series data to AI agents over the Model Context Protocol. Once connected, an agent can discover your vessels, look up which sensors are available, and pull aggregated statistics directly in a conversation, without you writing any API calls.

The server is available at:

https://mcp.raalabs.io/{ENVIRONMENT}/mcp

Replace {ENVIRONMENT} with your tenant name: the same one you use in the portal URL portal.raalabs.io/{ENVIRONMENT} and in the REST API base URL.

Availability: The MCP server is enabled per tenant, and connecting requires an OAuth Client ID issued by Raa Labs for your tenant. To have it enabled, contact [email protected].

MCP or the REST API?

Both serve the same underlying data, and they suit different jobs.

Use the MCP server when	Use the REST API when
You want to explore data conversationally: asking questions, following up, and iterating inside an AI agent.	You are building an application, dashboard, or scheduled job.
You want an agent to find the right sensors for you rather than looking up tag names yourself.	You need raw, un-aggregated measurements.
You want quick answers and visualisations without writing code.	You need a specific response format, such as NDJSON or Parquet.
You are working ad hoc and do not want to manage tokens in a script.	You need the specific naming standards as input/output.

The MCP server is a layer over this same API, so everything it returns follows the API version 2026-09-10 response shapes documented in this space.

What you can ask

Once connected, the agent has tools for discovering vessels and sensors, querying aggregated statistics, reading time series metadata, and plotting vessel positions. You do not need to know tag names or query syntax in advance, the agent works that out itself. A few examples to start with:

• "Which vessels do I have access to?"

• "What sensors are available on IMO1234567?"

• "What was the average main engine shaft power across the fleet last week?"

• "Show me where my fleet is right now."

• "Compare daily fuel consumption for IMO1234567 and IMO7654321 over the past month."

Tip: Narrow broad questions where you can. Asking for every sensor on every vessel over a long period returns a lot of data at once, and a more specific question gives a faster, better answer.

Connecting a client

What you'll need

Item	Description
Tenant name	Your tenant identifier, the same as in your portal URL portal.raalabs.io/{ENVIRONMENT}.
MCP server URL	https://mcp.raalabs.io/{ENVIRONMENT}/mcp
OAuth Client ID	Issued by Raa Labs for your tenant. Required for the Claude connector.
API credentials	Your Client ID and Client Secret, as described under Authentication. Required for the Claude Desktop route.
Node.js 18+	Required for the Claude Desktop route only, to run npx.

Important: Handle your Client ID and Client Secret with care. Do not share or expose these credentials in source code, public repositories, or unsecured locations. If you suspect that a Client Secret has been compromised, contact Raa Labs support immediately to regenerate it.

Setup

Claude connector

This is the recommended way to connect. An administrator adds the connector once for the whole organisation, and each team member then activates it with their own sign-in, so data access follows each person's own permissions.

Note: Adding a connector for the whole organisation requires the Owner role on a Claude Team or Enterprise plan. Custom connectors are currently a Beta feature in Claude, so the dialog is labelled accordingly and its wording may change.

For administrators

1. In Claude, go to Settings → Connectors.

2. Click the + button at the top of the panel, then choose Add custom connector. Do not use Browse connectors: that opens Anthropic's pre-built catalogue, which does not include the Raa Labs MCP.

3. Enter a Name your team will recognise, for example Raa Labs MCP.

4. Enter the URL of your tenant's endpoint: https://mcp.raalabs.io/{ENVIRONMENT}/mcp

5. Expand Advanced settings and paste your OAuth Client ID. Leave the OAuth Client Secret field blank.

6. Under How your team connects, keep Individual sign-in selected. Do not select Managed authorization.

7. Click Add. The connector appears in the Connectors list, tagged CUSTOM.

For team members

Once an administrator has added the connector it is available to everyone in the organisation, but because it uses individual sign-in each person signs in once:

1. Go to Settings → Connectors and find Raa Labs MCP in the list.

2. Click Connect and complete the sign-in prompt with your Raa Labs account.

3. In a chat, open the tools menu next to the message box and make sure Raa Labs MCP is enabled for that conversation.

Claude remembers the connection for future chats. If the tools stop appearing, return to Settings → Connectors and reconnect.

Claude Desktop

Claude Desktop connects through mcp-remote, a local bridge that forwards requests to the MCP server. This route uses your API credentials directly rather than an interactive sign-in.

1. In Claude Desktop, go to Settings → Developer → Edit Config. This opens claude_desktop_config.json:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add an mcpServers entry. If the file already has other servers, add this entry inside the existing object.

{
  "mcpServers": {
    "raalabs": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.raalabs.io/{ENVIRONMENT}/mcp",
        "--header",
        "Authorization:Basic BASE64_CREDENTIALS"
      ]
    }
  }
}

Replace the placeholders:

Placeholder	What to use
{ENVIRONMENT}	Your tenant name
BASE64_CREDENTIALS	Base64-encoded client_id:client_secret

Generate the encoded credentials from a terminal:

echo -n "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" | base64

1. Fully quit Claude Desktop (Cmd+Q on macOS, or right-click the system tray icon and choose Quit on Windows) and reopen it.

Other MCP clients

Any MCP-compatible client can connect. The details it needs:

Property	Value
Endpoint	https://mcp.raalabs.io/{ENVIRONMENT}/mcp
Transport	JSON-RPC 2.0 over HTTP. POST only. GET and DELETE return 405 Method Not Allowed.
Authentication	Standard Authorization header, forwarded on every request.
Server name	raalabs-mcp
Protocol version	2026-07-28. The earlier revisions 2025-11-25, 2025-06-18, and 2025-03-26 are also accepted.

Note: There is no stdio transport and no server-sent event stream. Clients that expect a stdio server should use a bridge such as mcp-remote, as shown in the Claude Desktop tab.

Verify the connection

Ask the agent to list your vessels. For example, "List the vessels available in the Raa Labs MCP". It should return your fleet with vessel names and IMO numbers. If it does, you are connected.

Troubleshooting

Symptom	What to check
Tools don't appear after connecting	For the connector, confirm it is enabled in the conversation's tools menu. For Claude Desktop, check Settings → Developer for error logs, typically a JSON syntax error or npx not being found.
npx not found (Claude Desktop)	Claude Desktop launches servers with a minimal PATH, so npx may not resolve even though it works in your terminal. Use its full path as the command value: run which npx on macOS or Linux, or point at npx.cmd in your Node.js install directory on Windows.
Authentication errors	For the connector, confirm the OAuth Client ID is correct and that you completed the individual sign-in. For Claude Desktop, re-run the base64 command to check your encoded credentials. If a Client ID has been reissued, update it.
Errors mentioning a status code	The connection is working. This is an error from the underlying API surfaced as a tool result. The status codes and messages follow the Response Codes and Error Handling page.
No data returned	Confirm your tenant has vessels with data flowing, and that your credentials grant access to them. Ask for your vessel list first to check basic connectivity.