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.

Add the server 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. 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. Review the client name, requested scope, and key shown on the consent screen. Approve only the app you intend to connect, then return to the MCP client.
5. Discover the tools and try 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 require Growth or Enterprise.
• 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.

verify_uk_vatis feature-gated: it is not advertised when HMRC integration is disabled. Use the client's tool discovery to check what the server currently offers.

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. 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.