Connecting AI Assistants to Raal (MCP)

Raal exposes a Model Context Protocol (MCP) server so you can connect AI chat assistants (Claude, ChatGPT, and other MCP-compatible clients) directly to your Raal company data. Once connected, you can ask your assistant questions about your orders and company account in natural language.

What you need

• A Raal API key for your company. If you don't have one yet, contact your Raal account manager or support to have one generated.

• An MCP-compatible AI client (e.g. Claude, ChatGPT, or any client that supports remote MCP servers over Streamable HTTP).

Connection details

Authentication

Every request must include your company API key. Depending on what your AI client supports, use one of the following:

Option A — Authorization header (preferred)

Authorization: <your-api-key> 

Option B — Query parameter (fallback)

Some MCP clients don't allow setting custom headers. In that case, append the key as a query parameter instead:

https://customerportal-api.raal.io/mcp?api_key=<your-api-key> 

Optional — acting as a specific user

By default, the assistant acts as the default user associated with your API key. If your company has multiple employees with Raal accounts and you want the assistant to act on behalf of a specific person (respecting that person's permissions), add:

email: <employee-email> 

That employee must already exist as a user on your Raal company account.

Example client configuration

For clients that accept a JSON config for remote MCP servers:

{ "mcpServers": { "raal": { "url": "https://customerportal-api.raal.io/mcp", "headers": { "Authorization": "<your-api-key>", "email": "you@yourcompany.com" } } } } 

What's available today

All tools are read-only and scoped to your own company's data — the assistant can never see or modify another company's information.

Example things you can ask your assistant:

• "What orders do we have open right now?"

• "Show me the details of order #12345."

• "What's on our company profile / current settings?"

Limitations

• Read-only. The assistant cannot place, edit, or cancel orders through MCP — use the Raal customer portal for that.

• Scoped to orders and company profile only. Pricing, shipment tracking, invoicing, and other areas aren't yet exposed via MCP.

• Users without viewer permission on the Raal portal won't be able to list or view orders through the assistant either — permissions match the portal exactly.

Notes about different AI assistance connections

Chat GPT

Chat GPT usually doesn’t allow to use custom headers in requests, if that is also case for you then just use url with api key in it and choose “No Auth” for Authentication. Your api key then should be configures with email, that will be used to identify user in Raal system.

Claude

When adding custom connector in Claude, there is no place for custom headers, so you need to use url with api key in it and leave OAuth setting fields empty.

After adding customer connector and clicking on Connect, it very often shows error. It is known behavior for Claude - you need to close all windows with Claude, wait 2-3 minutes and open again. Usually it should be connected.

Troubleshooting

Security note

Treat your Raal API key like a password — anyone with it can read your company's order data through this connection. Don't share it outside your organization or paste it into public or untrusted tools.