Skip to main content

Connecting an MCP

The Model Context Protocol (MCP) lets AI assistants and agents connect to external tools and data. An MCP client that connects to Lexabit can read and act on a user's Lexabit data on their behalf — so the authorization has to be user-consented and tightly scoped.

MCP clients connect to Lexabit as OAuth Connectors. The MCP authorization spec is OAuth 2.1 — the same authorization-code + PKCE + discovery flow documented in Connectors & OAuth. This page covers the MCP-specific details; that page has the full step-by-step.

How it fits together​

An MCP connection is a Connector: when a user authorizes it, Lexabit mints a scoped App and a Token bound to the one entity the user consented to. The MCP client stores that token and calls the API as that App.

Users never see the words "Connector" or "App" — the Portal shows your product's own name and logo, and files the connection under Connected by you or Member-connected tools depending on who owns it (term reference).

Scoped by construction

Each user's authorization produces its own App on its own entity, so an MCP client only ever reaches the accounts a given user consented to — never "all accounts." Isolation is structural, the same as any Connector.

Recommended: request delegated access

A plain connection only sees what was directly granted to the App. For an AI assistant working with a user, request delegated access too — add the literal token delegate to your scope (e.g. scope=viewer delegate). If the user picks it on the consent screen, your client sees what they see within the consented scope, while its actions stay bounded by the granted roles — and the user can revoke everything with one click in Connections. This is the preferred pattern for agents — never ask a user to paste a personal access token into a hosted service; that hands over their full identity with nothing to constrain it. Delegate mode must be enabled on your connector at registration (below).

To the user, this is not a checkbox called "delegation" — it is the option "My own tool — seeing my view", and afterwards their connection simply reads "Sees Lexabit as you do." Use those words when you explain the permission you are asking for (term reference).

What an MCP client needs​

  1. Discovery — read the authorization-server metadata to find the endpoints:

    GET https://api.lexabit.com/.well-known/oauth-authorization-server

    It advertises the authorization_endpoint (/oauth/v1/authorize), the token_endpoint (/oauth/v1/token), and the supported PKCE methods.

  2. PKCE — Lexabit requires code_challenge/code_verifier (S256). This is mandatory for MCP clients; there is no implicit or password grant.

  3. A registered connector — see below.

Registering your MCP connector​

Local clients: no registration needed​

If your MCP client runs on the user's own machine (a desktop assistant, a CLI agent), use the shared public connector — there is nothing to register:

Client IDctr_local_ai_assistant
Redirect URIhttp://127.0.0.1:<any port>/callback or http://localhost:<any port>/callback
Client typePublic — no secret; PKCE (S256) required
Delegate modeEnabled — request scope=viewer delegate
Role ceilingviewer (read-only)

Loopback redirect URIs are matched port-agnostically (RFC 8252): bind any free port at runtime and use it in your redirect_uri — the host and the /callback path must match exactly, only the port is free. This is safe because the client is public and PKCE binds each authorization code to the process that started the flow; a shared client_id carries no secret and grants nothing by itself — every access still requires the user's consent.

The shared connector is deliberately capped at the read-only viewer role. Combined with delegated access (opt-in on the consent screen), that is the right shape for an assistant working with a user: it reads what the user sees, and nothing more.

Hosted services: administrative registration​

A hosted MCP service has its own https redirect URI, which cannot ride the shared connector — it needs its own registration. MCP dynamic client registration (RFC 7591 — where a client self-registers automatically) is not yet supported, so registration is administrative: contact Lexabit to register your connector. You'll provide:

  • a name and branding (shown on the consent screen),
  • the redirect URI(s) your MCP client uses (matched exactly; http loopback URIs are matched with any port per RFC 8252), and
  • whether you'll authenticate with a client_secret or PKCE only (public clients use PKCE only).

You'll receive a client_id (and a client_secret if applicable).

The flow, briefly​

  1. Discover the endpoints (.well-known above).
  2. Send the user to GET /oauth/v1/authorize with your client_id, redirect_uri, scope, and a PKCE code_challenge.
  3. The user logs in, chooses what kind of connection this is (an organization integration, their own tool, or their own tool seeing their view), and approves — for a specific scope.
  4. Exchange the returned code (+ code_verifier) at POST /oauth/v1/token for a bearer token. The response also carries a refresh_token; MCP clients that implement OAuth 2.1 refresh it automatically, so the connection keeps working after the one-hour access token expires (see Keeping access alive).
  5. Call the API as that scoped App, sending the App's scopeId in X-Scope.

See Connectors & OAuth for the full request/response detail of each step.

Where to go next​