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

# Reach Developer MCP (Beta)

> Connect an AI coding assistant to the read-only Reach API

<Warning>
  The Reach Developer MCP is in **Beta**. Its endpoint, available capabilities, and client compatibility
  may change before general availability. Do not make it a production dependency.
</Warning>

The Reach Developer MCP lets an AI coding assistant explore your Reach
integration using partner-wide operations and tenant-scoped operations for
tenants your organization owns. It is useful during onboarding for inspecting
tenants, schemas, mappings, resource counts, channel integrations, and product
configuration.

The MCP is read-only. It cannot create, update, or delete Reach data.

<Warning>
  API responses are shared with the configured AI client and model. Administrators should connect only an
  AI provider approved for their production data.
</Warning>

## Before you connect

You need:

* A Reach partner account with a WorkOS organization connected by Reach
* The `admin` role in that WorkOS organization
* An MCP client that supports remote HTTP servers and browser-based OAuth

You do **not** need to copy a Reach API key or JWT secret into the MCP client.
Authentication happens through WorkOS AuthKit in your browser.

<Note>
  The selected WorkOS organization determines the Reach partner. Partner routes span that partner, while
  tenant routes require a Reach tenant ID or your external tenant ID. The MCP verifies that tenant
  belongs to the authenticated partner on every tenant-scoped call.
</Note>

## Connect your MCP client

Use this remote MCP server URL:

```text theme={null}
https://mcp.embedreach.com/mcp
```

### Codex

Add the server from a terminal:

```bash theme={null}
codex mcp add reach-developer --url https://mcp.embedreach.com/mcp
```

<Note>
  This command adds the server to your global Codex configuration. To limit the connection to one
  trusted repository, add it to `.codex/config.toml` in that repository instead:

  ```toml theme={null}
  [mcp_servers.reach-developer]
  url = "https://mcp.embedreach.com/mcp"
  ```
</Note>

Codex normally opens the authorization flow automatically. If authorization is
still required, run:

```bash theme={null}
codex mcp login reach-developer
```

### Other MCP clients

1. Add a remote or streamable HTTP MCP server.
2. Enter `https://mcp.embedreach.com/mcp` as the server URL.
3. Choose OAuth authentication if the client asks for an authentication method.
4. Sign in through WorkOS and select the partner organization you want to use.
5. Approve the connection.

The client discovers the OAuth configuration from the MCP server. Do not enter
a client secret or manually create a bearer token.

## What your assistant can use

The MCP exposes one action tool:

### `execute_reach_api`

Runs a GET request against a Reach API route. The MCP chooses the partner from
the verified WorkOS organization; the model cannot provide or override the
partner ID.

For a partner-wide `/partner` path, provide only `path`. For a tenant-scoped
`/api` path, also provide `tenantId`, using either the Reach tenant ID or the
external tenant ID configured by your platform. The MCP validates the tenant
against the authenticated partner and supplies the `reach-tenant-id` header.

Available operations include:

* Approved tenant-scoped GET routes under `/api`
* Approved partner-wide GET routes for tenant records
* Approved partner-wide GET routes for schemas, mappings, resource counts,
  channel integrations, and aggregate Voice reporting

The MCP also publishes Reach API and integration documentation as resources so
your assistant can look up an endpoint before calling it.

<Info>
  The MCP rejects write methods, arbitrary URLs, tenant IDs not owned by the authenticated partner, and
  tenant or partner routes outside its reviewed allowlists.
</Info>

## Example prompts

* “Use the Reach Developer MCP to list my tenants.”
* “For tenant `acme-location-42`, list its segments and summarize how they are configured.”
* “Show the schema definitions configured for this partner.”
* “Summarize resource counts by tenant without listing individual records.”
* “Read the Reach API documentation and explain how schema mappings work.”
* “Show aggregate Voice call activity for the last seven days.”

Your assistant may ask permission before invoking the tool, depending on the
client's tool-approval settings.

## Switching between partner organizations

An OAuth grant is scoped to one WorkOS organization. If you administer more
than one Reach partner—for example, production and development partner accounts
whose organizations are both configured in Reach's production WorkOS
environment—authorize a separate named MCP connection for each organization,
or log out and authorize again when switching.

Each connection remains isolated: requests made with one organization's token
resolve only to the Reach partner mapped to that organization.

## Troubleshooting

### The organization is rejected

Confirm that:

* You selected the intended WorkOS organization.
* Your membership role in that organization is `admin`.
* Reach has connected that WorkOS organization to the expected partner account.

### The client does not open a browser

Use the client's OAuth login or reconnect action. For Codex, run:

```bash theme={null}
codex mcp login reach-developer
```

### A requested API path is unavailable

The Beta MCP exposes reviewed sets of tenant-scoped and partner-wide GET routes.
For a tenant-scoped path, confirm that it is listed in the MCP's API resources,
that you supplied the intended Reach tenant ID or external tenant ID, and that
the tenant belongs to this partner. Ask the assistant to inspect the MCP's
Reach API documentation, or use the [API Reference](/api-reference/introduction)
directly.

For access or Beta feedback, contact your shared Reach Slack channel or
[support@embedreach.com](mailto:support@embedreach.com).