Documentation

Hosted MCP setup

The hosted EpiDev MCP server is provisioned from the customer portal and reachable over HTTPS, so assistants that can only talk to a remote MCP server — ChatGPT, and Claude on the web and desktop — can use EpiDev tools without a VS Code window open. Claude Code connects to the same endpoint. This page covers seats, provisioning, policy, each client, and how to take access away again.

How hosted MCP works

A hosted server belongs to one organization. It holds the ERP environments you register with it, enforces the same mode and agent-write policy the extension enforces, and presents EpiDev's tools to any MCP client you authorize. People reach it with named seats, not with a shared key.

Your endpoint is your own There is no universal EpiDev MCP URL. Your server endpoint is specific to your organization, and the only correct copy of it is the one shown in the portal. Copy it from there rather than typing it from memory or reusing one from a colleague's screenshot.

How clients authorize

Clients sign in with the OAuth 2.0 authorization code flow with PKCE. The server also supports dynamic client registration, so a client registers itself the first time you add it: there is no client ID or secret for you to create, and nothing of the kind to paste into a chat window. The sign-in is where your seat is checked, which is why the seat has to exist first.

The order of the work

Assign the named seats people will use — see Seats and pricing.
Provision the server and copy its endpoint — see Provision in the portal.
Register at least one ERP environment — see Add an ERP environment.
Set the mode and agent-write policy for each environment — see Policy and permissions.
Connect each client and complete its sign-in.
Prove it works with a read that cannot change anything — see Test a safe read.

Using EpiDev inside VS Code instead? The extension runs its own MCP server bound to 127.0.0.1, connected with EpiDev: Connect Agent Clients. That is a different setup with different trade-offs, and it is covered in Use AI agents. The two can coexist; they do not share configuration.

Seats and pricing

Hosted access is per named person. Each person who will use an assistant against your ERP needs a seat of one of two types, assigned to them in the portal.

Seat types. Prices are per named user per month, in USD.
Seat	Price	What the seat allows
Read-write	$30 / user / month	Everything a read-only seat can do, plus the tools that preview and apply changes — still subject to the environment's mode, its agent-write policy, any per-domain overrides, and the ERP user's own permissions.
Read-only	$5 / user / month	Listing, reading, inspecting, analyzing, comparing, and diagnosing. Mutating tools are not offered to the client at all, and a mutating call is refused if one is attempted.

A read-write seat also reads Read-write is not a separate, write-only mode you would hold in addition to read-only. It is the read-only tool surface plus the mutating tools, so one seat per person is enough. It also never widens what an environment allows: on a readonly or live environment, a read-write seat still sees only read tools, and agentWrites still applies on a writable one. If most of your team only needs to look things up, read-only seats are the cheaper and safer default.

Assign seats before anyone authorizes a client The seat check happens during the OAuth sign-in. If someone adds the connector in ChatGPT or Claude before their seat exists, the authorization is refused, and they will need to remove the connector and add it again once the seat is in place. Assigning seats first avoids that round trip entirely.

Seat type and seat count are managed in the portal. The server license is $120 per server per month, a separate line on your bill and is not changed by how many seats you assign or which type they are. EpiDev extension plans are priced separately again — see Get EpiDev.

Provision in the portal

Provisioning and seat assignment are owner and admin actions. Everything in this section happens at portal.epidev.ai; nothing here is configured from a chat client.

Sign in to the portal. Use an account that owns or administers the organization. A member account can hold a seat but cannot provision a server or assign seats.
Provision the hosted MCP server. Open MCP Server > Servers, select Create hosted server, enter a name, and wait for Ready. One server serves the whole organization; you do not need one per person or per client.
Assign named seats. Open Seats, add each person who will connect an assistant, and choose read-write or read-only for them. Do this before they touch a client — see Seats and pricing.
Copy the server endpoint. The portal shows the complete HTTPS URL for your server. Copy it with the portal's own copy control rather than retyping it: it is the exact value ChatGPT, Claude, and Claude Code each need, and it already carries the MCP path those clients expect.

Add an ERP environment

An environment is one ERP instance plus the policy that governs it. A hosted server with no environment registered has nothing to read, so add at least one before you connect a client. You can register several and let callers choose.

What each environment needs. The vocabulary matches the extension's, so a profile reads the same in both places.
Field	What to enter
Name	A unique key for this environment. It appears in tool parameters, results, and audit entries, so pick something a person can recognize in a chat transcript.
Base URL	The instance root, for example `https://host/Instance`. REST paths are built from this value plus `/api/v2/…`.
Company	Default ERP company segment for REST v2 OData and RPC calls.
Authentication	Either an ERP user with its password and `x-api-key`, or the tenant's SSO configuration. Whatever you choose, the ERP side decides what that identity may touch.
Mode	`readonly`, `writable`, or `live`. Start at `readonly` and move an environment only when you mean to.
Agent writes	`deny`, `confirm`, or `allow` — the policy applied to AI clients specifically, on top of the mode.
Domain overrides	Optional per-domain narrowing, for example keeping AppStudio read-only inside an otherwise writable environment.

Finish with the portal's connection test. A passing test confirms the instance answered, which identity it resolved, and the live server version. If it fails, re-check the base URL shape, the company, and the stored credentials before changing anything else.

Credentials belong in the portal only Enter ERP passwords, API keys, and SSO details in the portal. Never put them in a connector name or description, in a ChatGPT or Claude request header, or in a chat message. Nothing about EpiDev authorization requires a fixed header: the OAuth sign-in carries it.

Policy and permissions

Five independent things decide whether a given call is allowed. They narrow, they never widen: the most restrictive one wins, and no setting inside a chat client can loosen any of them.

Each gate a call passes through, from the person to the ERP.
Gate	What it decides
Seat type	Whether mutating tools are offered to this person at all. A read-only seat never sees them.
Environment mode	`readonly` and `live` are read-only for everyone, humans and agents alike. `writable` is the only mode in which anything is written.
Agent-write policy	On a `writable` environment, whether an AI client's write is denied outright, requires an explicit confirmation, or proceeds through the normal gate and audit path.
Per-domain overrides	Narrows single domains below the environment's own setting, and only downward.
ERP permissions	The final word. The ERP identity the environment authenticates as still governs what the instance will return or accept, exactly as it would for that user signing in directly.

Read this once live does not mean "writes allowed on the live system". It is the strictest level: read-only everywhere, with agent writes forced off. If you intend to write, the environment must be writable. The same distinction is explained in more detail under Safety modes.

Granting someone a read-write seat is therefore a decision about that person, not about your environments. Deciding which environments can be written at all is a separate decision you make per environment, and it is the one that protects production.

Connect ChatGPT

ChatGPT adds a remote MCP server as a plugin. You need your seat assigned and your server endpoint copied before you start.

Check your workspace policy first Account and workspace policies apply to adding and using custom MCP servers. In a managed workspace an administrator may have to allow them before the option appears or before the plugin can be installed.

Open ChatGPT Plugins. Go to chatgpt.com/plugins.
Select the plus button, then Add custom MCP server.
Enter a name and description. These are user-facing, and they are what you will recognize later when selecting the plugin in a conversation. EpiDev plus a line naming the ERP environments it reaches is plenty.
Paste your server endpoint as the MCP server URL. Use the public HTTPS endpoint you copied from the portal, including its /mcp path. If you shortened or re-typed it, go back and copy it again.
Configure authentication and acknowledge the risk warning. Read the warning, then select I understand and want to continue. EpiDev's server advertises its own OAuth configuration, so there is no client ID or secret to supply here.
Select Create as a plugin, then review the tools. ChatGPT shows the tools and metadata it discovered from your server. This is a good moment to confirm the surface matches your seat: a read-only seat should show no mutating tools.
Install it, then use it with @. Open a new conversation, type @ in the prompt box, and select the plugin. You will be sent to EpiDev to sign in and approve access the first time it is used; that sign-in is where your seat is checked.

If you find older instructions Write-ups that begin by switching on a developer mode describe an earlier flow. Adding a custom MCP server now runs through ChatGPT Plugins as above; check any third-party instructions against OpenAI's current Connect to ChatGPT documentation before following them.

Connect Claude web & desktop

Claude calls a remote MCP server a custom connector. The steps are the same on the web and in the desktop app.

Team and Enterprise: the owner goes first On Team and Enterprise plans an organization owner must add the connector under Organization settings > Connectors — Add > Custom > Web — before members can connect it. Members then follow the steps below to connect it to their own account. On individual Pro and Max accounts there is no such prerequisite; start at step 1.

Open Customize > Connectors.
Click + Add, then Add custom connector.
Enter a connector name. EpiDev is the obvious one; if you run more than one server, name the organization or environment group it reaches.
Paste your server endpoint and click Continue. Use the exact URL copied from the portal.
Review the authentication settings and click Continue. Under Authentication, choose Sign in now so you find out immediately whether your seat is in place, rather than at the moment you first need a tool.
Under OAuth client, choose Register automatically. This lets Claude register its own client with your server through dynamic client registration.
Leave Request headers empty. EpiDev authorization travels through the OAuth sign-in. Fixed header credentials are for servers that work differently, and ERP credentials never belong here.
Click Add and complete the sign-in. Approve the access request on EpiDev's page. The connector then appears in your connector list and its tools become available in chat.

OAuth client registration Select Register automatically for this setup. EpiDev supports dynamic client registration, so you do not need to enter a client ID or client secret.

Connect Claude Code

Claude Code reaches the same endpoint over HTTP transport, added from the command line. Replace <copied-endpoint> with the exact URL from the portal:

claude mcp add --transport http epidev <copied-endpoint>

Then start Claude Code in that project and run:

/mcp

/mcp lists the configured servers, starts the browser sign-in for epidev if you have not authorized yet, and shows the tools once the server is connected. Use it again later to re-authenticate if a session expires.

Scope By default the server is added for the current project. Add --scope user to the claude mcp add command instead if you want it available in every project on your machine.

Treat the endpoint as internal The endpoint identifies your organization's server. It is not a password, but it is not public either: keep it out of public repositories, issue trackers, and screenshots, and let each person copy their own from the portal.

Test a safe read

Prove the connection with calls that cannot change anything, against a readonly environment. In order, these answer "am I authorized, to what, with which permissions" before anything else is attempted:

epi_environments — confirms the sign-in worked and lists each environment, its effective mode, and its agent-write policy. It never returns secrets.
epi_tool_catalog — shows exactly which tools your seat and the active environment expose. On a read-only seat, mutating tools are absent from this list.
epi_list_artifacts — compact rows for one domain, narrowed by a search term.
epi_get_artifact — the content of a single artifact.

A prompt that walks the whole sequence:

Use EpiDev to list my environments with their modes, then list five BPM directives from the read-only one and summarize what they do. Do not change anything.

Expect the client to ask for your approval the first time it uses the connector, and expect the results to name the environment they came from. If the environment is named and the modes look right, the connection is good.

Missing write tools are not always a fault A read-write seat pointed at a readonly or live environment sees read tools only, and that is the system working as designed. Check the environment before you suspect the seat — see Policy and permissions.

Troubleshooting

Most first-connection problems are one of these, and most of them are fixed in the portal rather than in the client.

Symptoms and what to do about them.
Symptom	What to do
Sign-in is refused, or it completes but no tools appear	The most common cause is a missing seat, or a seat assigned after the client was added. Assign the seat in the portal, then remove and re-add the connector so it authorizes again.
Claude's sign-in fails after choosing the recommended OAuth option	The published-identity option is not supported by EpiDev's server. Remove the connector, add it again, and under OAuth client choose Register automatically.
ChatGPT cannot connect to the URL	Confirm you pasted the portal endpoint exactly, over HTTPS and including its `/mcp` path. OpenAI's documentation suggests verifying the endpoint with MCP Inspector before changing anything else.
The option to add a custom MCP server or connector is not there	This is a plan or policy limit, not an EpiDev one. In ChatGPT, account and workspace policy governs custom MCP servers. In Claude Team and Enterprise, an owner must add the connector under Organization settings > Connectors before members can connect it.
A read-write seat sees no write tools	Check the environment, in this order: its mode is `readonly` or `live`; a per-domain override narrows the domain you are working in; or its agent-write policy is `deny`. All three are portal settings, and all three outrank the seat.
It worked before and now asks you to sign in repeatedly	The authorization expired or was revoked. In Claude Code run `/mcp` and sign in again; in Claude or ChatGPT, reconnect the connector. If it is refused, check whether the seat is still assigned.
Results come back from the wrong environment	More than one environment is registered and the call used the active one. Name the environment explicitly in your request, so the assistant selects the intended ERP instance.

If none of these fit, note which client you used, which environment, and what the error said, and send it to support@epidev.ai. Do not include ERP credentials or customer data in the report.

Revoke access

There are three levers, and they are independent. Choose by how much you need to stop.

Disconnect one client

Stops that one assistant and leaves the person's other clients and their seat alone. In Claude, remove the connector under Customize > Connectors. In ChatGPT, remove the plugin. In Claude Code:

claude mcp remove epidev

Unassign the seat

Stops one person across every client they have connected, including ones you do not know about. Do this in the portal. It is the correct action when someone leaves, changes role, or no longer needs ERP access.

Revoke at the server

Use Unlink server in the portal to revoke that server and end its client access.

Removing a connector does not release a seat Deleting a connector in a chat client only changes that client. The seat stays assigned and the person can reconnect. Unassigning a seat frees it for another member; it does not change the purchased seat count or recurring bill. For offboarding, unassign the seat — and if that person knew an environment's ERP credentials, rotate those too.