Connect an agent through MCP and OAuth

Connect a client that supports remote HTTP MCP servers to Rotuli. This walkthrough uses OAuth so you can authorise a connected app without copying an API key. Direct API-key authentication is also supported for MCP clients that can securely send an Authorization header.

Connect from the Claude Connectors Directory

In Claude, the simplest route is the Rotuli listing in the Claude Connectors Directory. Open the listing (or search for Rotuli under Customize, then Connectors), then choose Connect. Rotuli is listed as a Community connector. The authorization steps below are the same.

Or add the server endpoint yourself

For another client, or to add the server by hand, use this endpoint:

https://api.rotuli.co.uk/mcp

In Claude, add this URL as a custom remote connector through the connector UI, then choose Connect. Claude Desktop's local server JSON configuration is a separate mechanism; a URL-only server map is not a universal configuration. Follow the official Claude connector instructions for your account. Other clients need their own remote HTTP and OAuth setup instructions.

Complete delegated authorization

1. Start with a Rotuli account that has an active API key. Connect from the directory listing, or add the endpoint and start the client's OAuth connection flow.
2. If prompted to sign in, enter your Rotuli account email on the API's connection page. This flow uses an emailed magic link, not your dashboard password.
3. Open the emailed link in the same browser session that requested it, then press the confirmation button. Opening the link alone does not complete sign-in; a different browser session will be rejected.
4. On the consent screen, check where your approval will be sent. The screen names the address you'll be returned to; for Claude it reads “You'll be returned to claude.ai”. An app chooses its own name, so trust this address, not the app name. If no address is shown, continue only if you trust the app.
5. If the screen warns that the app runs on your own computer (a local address), approve only if you started the connection yourself just now, for example from a command-line tool.
6. Check the requested scope and the API key the connection will use, then approve and return to the MCP client.
7. Discover the tools and try get_account_status to confirm the plan the connection uses, then lookup_uk_company with a company number, or search_uk_companies with a company name.

OAuth uses your highest-tier active API key (Enterprise, then Growth, then Free), resolved on each request. It does not let you choose an arbitrary key. With no active key, the request fails with key_inactive. Authorised apps are visible in Dashboard → Connections; revoking a connection withdraws that app's grant without rotating your API key.

What an agent can ask for

• lookup_uk_company: retrieve an entity profile. Risk signals and land holdings require Growth or Enterprise; land titles are capped at 25 by default (land_limit, up to 200), and land_summary gives the full counts.
• search_uk_companies: find company numbers by name.
• get_company_risk: retrieve risk signals; Free keys receive risk_tier_required.
• get_officer_appointments: retrieve appointments for one Companies House officer ID; Free keys receive appointments_tier_required. One officer ID is not necessarily a person's complete history.
• get_company_control_graph: explore corporate PSC links and related-company findings; Free keys receive control_graph_tier_required. Read the control-graph guide for coverage and interpretation.
• get_account_status: check the plan, the tools it includes and the remaining monthly quota. This call does not count towards the quota.

Tier errors also carry current_tier, the plan of the key the connection uses.

Read the result for the tool you called

These tools return JSON encoded in MCP text content, not a single shared response schema. Successful entity lookups include sources_checked and sources_failed. Search returns query, total_results, and results; the risk tool returns company_number, risk_signals, and fetched_at. Do not expect source-coverage fields on every result. Check for an error field before interpreting the data, even when the MCP call itself completed.

Understand what consumes quota

Each tools/call consumes one request from the same key quota used by REST, except get_account_status, which is not counted. Initialization, tool discovery (tools/list), notifications, and ping do not consume quota. A key whose quota is already exhausted still receives a 429 response for these otherwise-free protocol messages. See the MCP server reference for the full billing rules.

OAuth is not an API key shortcut

An OAuth grant delegates access to a connected app. Alternatively, a trusted MCP client can send your API key as a Bearer token in the Authorization header. Use the client's secure credential or environment-variable mechanism; do not commit keys, embed them in public browser JavaScript, or paste them into agent prompts. A local client's protected credential configuration is not the same as publicly exposed browser code.

Keep the agent's conclusions bounded

Instruct the agent to report unavailable sources and unknown outcomes, rather than inventing a conclusion from a partial profile. For risk workflows, point it to the risk-screening guide: unknown and indeterminate checks are part of the result, not noise to omit.