Skip to main content
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.
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. Most MCP operations are read-only. A separate write tool supports the schema and sample-resource operations used during data onboarding. Write requests remain subject to the AI client’s approval controls. The MCP cannot delete Reach data.
API responses are shared with the configured AI client and model. Administrators should connect only an AI provider approved for their production data.

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

​
Connect your MCP client

Use this remote MCP server URL:

​
Codex

Add the server from a terminal:
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:
Codex normally opens the authorization flow automatically. If authorization is still required, run:

​
Claude Code

Add the server from a terminal:
The user scope makes the connection available across your local projects and worktrees. To keep it private to the current project, use --scope local instead. Start Claude Code, run /mcp, and authenticate reach-developer in your browser.

​
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 two action tools, a guided onboarding prompt, and portable documentation resources.

​
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.
This tool rejects write methods, arbitrary URLs, tenant IDs not owned by the authenticated partner, and tenant or partner routes outside its reviewed allowlists.

​
execute_reach_write

Runs an approved POST or PATCH request for data onboarding. Provide the HTTP method, API path, JSON body, and a concise changeSummary. For a tenant-scoped /api path, also provide tenantId. Replacing partner schema mappings also requires ifMatch. First read GET /partner/schema-mappings with execute_reach_api, then pass the returned etag value unchanged. If the mappings changed in the meantime, Reach rejects the replacement so you can read them again and review a fresh diff. The current write allowlist is: For tenant operations, tenantId is required and may be either the Reach tenant ID or your external tenant ID. The MCP verifies that the tenant belongs to the authenticated partner before sending the request. For partner operations, omit tenantId.
Schema mappings are replaced as one complete configuration. Read the current mappings first, review a full before-and-after diff, and send the complete resulting configuration. Omitting an existing mapping removes it.
The Developer MCP applies narrower limits than the underlying Reach API:
  • The JSON body may be no larger than 100 KiB (102,400 bytes).
  • A batch body may contain no more than 100 resources.
  • changeSummary is required, may contain up to 500 characters, and should not contain credentials or sensitive record values.
  • Only the method and path combinations in the table above are accepted. In particular, schema updates use POST, while individual and batch resource patches use PATCH.
Use the Reach API directly for production synchronization and historical backfills. Batch submission returns before processing finishes; use execute_reach_api to poll /api/batches/{batchId} and inspect validation errors.
No other write routes are exposed. The tool rejects GET, DELETE, arbitrary URLs, unreviewed POST or PATCH routes, and tenant IDs not owned by the authenticated partner. Schema deactivation, resource deletion, and configuration writes outside schema definitions and mappings are not available.

​
onboard_reach_data

Clients that support MCP prompts can start this guided workflow with an optional validation tenant, source-system description, and onboarding objective. The prompt directs the assistant through source-model discovery, schema and mapping review, approved writes, small record tests, asynchronous batch diagnostics, and raw resource reconciliation. The detailed workflow is also published as the portable reach://docs/guides/onboarding-developer-mcp-data-onboarding resource. Clients that do not expose MCP prompts can read that resource directly or use the Developer MCP Data Onboarding guide. Keeping the procedure in a resource makes the same versioned guidance available to agents, developers, and documentation readers; the prompt remains a short entry point.

​
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.”
  • “Create these approved schema definitions, install the reviewed mappings, and validate three synthetic records for tenant acme-test.”
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 Reach has provisioned separate partner accounts for your development, staging, and production environments, create one named MCP connection per environment. All connections use the same MCP URL; the name and OAuth authorization keep their credentials and tools distinct. Use names that make the target environment unmistakable, such as reach-development, reach-staging, and reach-production.

​
Codex

Complete each browser flow separately and select the WorkOS organization that matches the connection name.

​
Claude Code

Start Claude Code, run /mcp, and authenticate each connection separately. Select the WorkOS organization that matches its connection name. If the tools do not appear immediately after authorization, restart the client.

​
Target an environment

Name the connection in your prompt so the assistant uses the intended tool namespace:
Use reach-development to list the partner’s tenants and schema definitions.
Before making changes, start with a read-only request and confirm that the returned tenants belong to the expected environment. Prefer a development or sandbox connection for onboarding writes and sample records. Each connection remains isolated: requests made with one organization’s token resolve only to the Reach partner mapped to that organization. If you authorized the wrong organization, clear authentication for only that connection and authorize it again. In Codex, run:
In Claude Code, run /mcp, select the connection, and choose Clear authentication before authenticating again.

​
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:

​
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 directly. For access or Beta feedback, contact your shared Reach Slack channel or support@embedreach.com.