> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up the MCP server

> Connect any Model Context Protocol (MCP)-compatible AI tool to Phrase.

The Phrase MCP Server lets an AI assistant work directly with your Phrase data. It can check job status, run quality checks, or start routine work in plain language, without opening Phrase or writing code. Any Phrase account with API access can use it.

## Connect

No installation, no tokens to manage. You sign in with your existing Phrase account.

**Prerequisites**

* An active Phrase account with access to the organization you want to connect
* An MCP-compatible AI tool that supports adding a remote server by URL

**1. Register the server**

Point your MCP client at the server URL for your region:

* EU: `https://mcp.eu.phrase.com`
* US: `https://mcp.us.phrase.com`

Check your Phrase account URL (`eu.phrase.com` or `us.phrase.com`) if you're not sure which region you're on. Exactly how you register a remote server depends on your client. Refer to its documentation for the precise steps. The server supports both Dynamic Client Registration (DCR) and Client Identifier Metadata Document (CIMD) for OAuth client registration.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport streamable-http phrase-mcp-prod-eu https://mcp.eu.phrase.com
> ```
>
> Use `phrase-mcp-prod-us` and the US URL if that's your region.

> [tab] ChatGPT
>
> 1. Go to **Settings → Plugins** and click **New Plugin**.
> 2. Enter a name (e.g., `Phrase`) and paste the server URL for your region. Leave the authentication method as OAuth.
> 3. Click **Create**.

**2. Authorize**

Start the authorization flow from your client. Sign in, pick your organization, and choose what to allow: View data, Create data, or Modify and delete data. Your normal Phrase role permissions still apply. This only restricts what you can do, it never expands it. You can change this later.

> [tab] Claude Code
>
> Run `/mcp` and select the Phrase server.

> [tab] ChatGPT
>
> Open the Phrase connector and click **Connect**.

**3. Confirm it's connected**

Ask your assistant to "fetch my most recent Phrase project."

You can view what you've authorized and revoke access anytime from your Phrase profile settings, under the Consents tab. This list is scoped to whichever organization you're signed into. If you connect to more than one organization, check each one separately. To see or manage consents for a different organization, sign out and back in under that organization first.

***

## Access and security

> [accordion] Whose permissions does the assistant use?
>
> The server acts as the signed-in user, with that user's existing role permissions in each Phrase product. There is no service account. The assistant can never see or do more than the user could in the product itself.

> [accordion] What does the consent level control?
>
> At authorization the user chooses View data, Create data, or Modify and delete data. The choice is checked on every request, for every product. Under View data, creating, changing, and deleting are blocked, and the tools for those actions are hidden from the AI client. The user's product role always applies as well, so the effective access is whichever of the two is narrower.

> [accordion] Can administrators manage consent centrally?
>
> No. Consent is given per user and per organization, with no per-project scoping, and administrators can't view or change other users' consents. User roles are the central control. To limit what an assistant can do for a team, limit the roles of its members.

> [accordion] What data does Phrase store, and is activity auditable?
>
> The server doesn't keep the AI client's prompts or conversation history, and it doesn't store the content of API responses. Phrase keeps technical request logs to operate and secure the service. They record that a call happened (time, product, type of operation, endpoint, permission level, outcome), not the request or response content. Endpoint paths can include identifiers of the records involved. Files transferred through the server are held temporarily and then expire.
>
> Changes made through the server are stored as normal Phrase data, attributed to the signed-in user, and appear in the product's usual history. Operational logs aren't currently available to customers as an audit trail.

***

## Connect a custom client

Most users never need this section. If you build your own MCP client or run an AI gateway, use the details below instead of a client's built-in setup.

### Endpoint and transport

* The server uses Streamable HTTP, with JSON-RPC 2.0 over `POST`. It is stateless: there is no session ID, and every request is self-contained. Responses are plain JSON, not an event stream.
* Send `Authorization: Bearer <token>` and `Content-Type: application/json`. The `Accept` header must include `application/json`. `text/event-stream` isn't required.
* `MCP-Protocol-Version` is optional. If you send it, it must be a version the server supports, or the request is rejected with a `400` error.
* Every request needs a token, including `tools/list`. An anonymous call returns `401`. The tool list is filtered per user based on their consent level, so run tool discovery with each user's token, and cache per user or per consent level.
* The server applies no rate limit of its own. Calls pass through to the product APIs (for example Phrase Strings and Phrase TMS), whose rate limits apply and can return `429`. Retry with exponential backoff.

### Authorization

The server uses the Phrase Platform authorization server, not a product-specific OAuth registration such as the one used for the Phrase TMS API. Read the authorization and token endpoints from the server's discovery metadata instead of hardcoding them.

* **Client registration:** besides Dynamic Client Registration and Client Identifier Metadata Document, Phrase can register a public client for you, with Proof Key for Code Exchange (PKCE) enabled, no client secret, and your exact redirect URI.
* **PKCE:** the `S256` challenge method is supported and recommended. For public clients PKCE is effectively required.
* **Client authentication:** a public client sends only `client_id` on the token request, with no `client_secret`. The discovery metadata lists only `client_secret_post` as a token authentication method, but `none` works. If your library validates against the metadata, set it explicitly.
* **Resource:** send `resource=https://mcp.eu.phrase.com` (or `https://mcp.us.phrase.com`) on the authorization request. This is the server's base URI, without a path. Don't send `audience`.
* **Scopes:** request `phrase-mcp:read`, `phrase-mcp:write`, and `phrase-mcp:destructive` as needed, for example `phrase-mcp:read` alone for read-only use. Don't request `offline_access` or a bare `read`, which are rejected. A refresh token is issued without them. The user's consent level and product role limit access further.
* **Token lifetimes:** access tokens last 4 hours. Refresh tokens last 30 days and are rotated: each refresh returns a new refresh token and invalidates the old one, so always store the new one.

***

## Troubleshooting

> [accordion] "Authentication failed" after signing in
>
> The sign-in didn't complete. Restart the authorization flow from your client and try again.

> [accordion] Nothing happens when you ask a question
>
> Confirm the server shows as connected in your client.

> [accordion] Permission errors
>
> The scopes you granted at authorization limit what the assistant can do. Your Phrase role permissions still apply in addition to them, not instead of them. Check what you allowed when you connected.

## What's next

Once you're connected, head to **[Starter prompts](https://developers.phrase.com/en/mcp-server-starter-prompts.md)** to see what to try first.

***

## Local install (deprecated)

Before the hosted server above, the Phrase MCP Server was a self-hosted, open-source package you ran yourself with your own API tokens. It's still available for teams already using it, but the connect flow above is now the recommended way to get started.

Setup, configuration, and troubleshooting for the local install live in the [phrase/phrase-mcp-server](https://github.com/phrase/phrase-mcp-server) README.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.