MCP connection setup

Connect to authenticated account tools, then verify the organization and tool inventory.

Connect your assistant to your Lingo.dev account, then confirm the intended organization with a read. The server acts as the signed-in Lingo.dev user.

Account connection #

Set the remote server URL to https://mcp.lingo.dev/mcp and select Streamable HTTP with OAuth. Start the client's authorization flow, sign in to the intended Lingo.dev account, and approve the connection. The client discovers the authorization server from the MCP endpoint and manages its access and refresh credentials.

The MCP request carries a user access token in Authorization: Bearer <access-token>. It is not a permanent personal API key and is not bound to one organization. The backend checks the user's access to the resources each tool names. Account credentials explains that authority and credential handling.

An API key in x-api-key, or an API key used as the bearer value, does not authenticate this hosted server. Use a client that supports its OAuth connection rather than copying an API key into a static header.

The connection values are summarized below. This worksheet is not a client-specific configuration file:

json
{
  "endpoint": "https://mcp.lingo.dev/mcp",
  "transport": "Streamable HTTP",
  "authentication": "OAuth user session"
}

Map these values to the fields your client supports. Authentication storage and configuration syntax vary by version. The endpoint accepts MCP POST requests: without a valid token it returns 401 with OAuth discovery metadata; an authenticated GET returns 405 Method Not Allowed. Opening the URL in a browser does not test an initialized MCP connection.

Existing hosted URLs #

https://mcp.lingo.dev/main serves the same tools and user authority. Its OAuth discovery flow differs from /mcp, so a working /main connection can keep its existing authorization configuration. When moving to /mcp, add it as a new connection and complete that URL's OAuth flow; do not mix an old connection's saved authorization settings with the new URL.

The earlier https://mcp.lingo.dev/account address returns 401 until it receives a valid user token, then 308 to /main, preserving the request method and body. That redirect does not restore API-key authentication or the old organization-bound tool catalog. Reconnect through OAuth when migrating a connection that held an API key.

Finish setting up a new organization #

A new account names its organization in the web app while connecting. The organization's creator then finishes three more steps there: integrations, teammates, and the first engine, which the web app fills from the organization's website. Integrations and teammates can be skipped. Until all three are done, every tool that names that organization returns an error that names the steps left and links to https://lingo.dev/orgs/<orgId>, which opens the step the creator is on. members_listMemberships still lists the organization, so the assistant can find its ID.

Open the link, finish the steps, then repeat the call. After that, the assistant works normally and can create more engines with engines_create or provisioningJobs_create. Invited members and organizations created before this setup existed are not affected.

Verify the account scope #

  1. Open the client's tool inventory and find members_listMemberships and engines_list.
  2. Call members_listMemberships to read the user's organizations. Use the sole organization when there is one; when several are available, choose the intended one and retain its ID for this task.
  3. Call engines_list with that organization's orgId, then choose an engine ID from its returned data.
  4. Read each selected tool's advertised schema before using it. Org-level tools take an explicit organization field; object-level tools can take a resource ID instead. Keep writes within the task's agreed scope.

Switching between organizations in the same membership list does not require another OAuth connection. Pass the selected ID in the field the tool declares, such as orgId or an organization id. The server does not inject a fixed organization from the token. If the signed-in person is wrong, reconnect through the client's account management.

members_listMemberships #

This call needs no organization ID. intent is optional and describes the task:

json
{
  "intent": "Find the organization whose French translation guidance I should inspect."
}

The response's data contains accessible organizations with their IDs and names. Optional ssoRequired entries identify memberships that require an SSO sign-in this session has not used. Sign in to Lingo.dev through that organization's identity provider, then reconnect. An organization in ssoRequired is not available to ordinary org-level calls yet.

If both lists are empty, open https://lingo.dev/orgs/start to set up the first organization, then repeat this read. Do not invent an organization ID or create a second organization merely because an existing membership needs SSO.

engines_list #

Replace org_example with an ID from the membership response:

json
{
  "orgId": "org_example",
  "intent": "Find the localization engine used for French translations."
}

Use an engine ID from the returned data for later engine-level reads. These are complete tool arguments, not HTTP payload wrappers. Tools use optional intent alongside their operation-specific fields. See Capabilities for the account operations.

Client-specific placement #

Use the client's current documentation for its configuration syntax and supported transports. These choices matter even when two clients use the same endpoint.

Claude Code #

Choose a remote OAuth HTTP connection for /mcp. Decide whether the connection belongs to your user configuration or the project before saving it. Project-shared settings must not contain credentials; each user should authorize their own account connection. Verify the inventory after enabling it.

Codex #

Codex uses TOML configuration, commonly in ~/.codex/config.toml. Configure the account URL through the version's remote MCP support. Do not transplant JSON from another client into TOML. If a transport bridge is required by your version, check the bridge's own authentication and token storage before using it; a bridge is another credential-bearing process.

Cursor #

Choose user-level settings or a project .cursor/mcp.json deliberately. A project connection lets teammates discover the server definition, but must not share a literal account key. Each user should authorize their own account connection.

Claude Desktop and claude.ai #

Lingo.dev is listed in the Claude connector directory, so no URL or configuration file is needed. The steps are the same in Claude Desktop and on claude.ai:

  1. Open Settings > Customize > Discover.
  2. Search for Lingo.dev and click Connect on the Lingo.dev connector.
  3. On the Lingo.dev Authorize page, sign in to the intended account and click Approve.

Claude stores and renews the credentials. Verify the inventory after connecting.

ChatGPT #

Remote custom-app availability and OAuth support depend on the account and client version. When that support is available, use the /mcp URL and authorize the intended Lingo.dev user.

Give the agent a bounded first task #

A first request could be:

Inspect the selected localization engine's French glossary and instructions. Explain which resources are attached and whether they address the product term I supplied. Propose any change before applying it. This task does not authorize translation, suggestion generation, key creation, or member management.

Pair the instruction with client-side approval or an appropriate tool allowlist. A prompt defines the requested work but does not remove write authority from a credential.

If discovery or the first read fails, use Troubleshooting to resolve it before continuing.