> For the complete documentation index, see [llms.txt](https://docs.raalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raalabs.io/docs/mcp.md). # MCP Server The Raa Labs **MCP server** exposes your fleet's time series data to AI agents over the [Model Context Protocol](https://modelcontextprotocol.io). 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. {% hint style="warning" %} **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 . {% endhint %} ## 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](/docs/api-endpoints.md) 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."* {% hint style="info" %} **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. {% endhint %} ## 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](/getting-started/authentication.md). Required for the Claude Desktop route. | | **Node.js 18+** | Required for the Claude Desktop route only, to run `npx`. | {% hint style="danger" %} **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. {% endhint %} ### Setup {% tabs %} {% tab title="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. {% hint style="info" %} **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. {% endhint %} #### 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. {% endtab %} {% tab title="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. {% code lineNumbers="true" %} ```json { "mcpServers": { "raalabs": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.raalabs.io/{ENVIRONMENT}/mcp", "--header", "Authorization:Basic BASE64_CREDENTIALS" ] } } } ``` {% endcode %} 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: {% code lineNumbers="true" %} ```bash echo -n "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" | base64 ``` {% endcode %} 3. Fully quit Claude Desktop (**Cmd+Q** on macOS, or right-click the system tray icon and choose **Quit** on Windows) and reopen it. {% endtab %} {% tab title="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. | {% hint style="info" %} **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. {% endhint %} {% endtab %} {% endtabs %} ### 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](/docs/error-handling.md) 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. |