Deployment

The Backend MCP Server is a container image (nhost/mcp) that you deploy alongside your project using Nhost Run. Running it next to your GraphQL API keeps latency low and lets it reach the API over the internal network.

Note

Check the releases page and use the most recent version of Backend MCP. The examples below pin nhost/mcp:0.1.0 — update the tag as needed.

Before you deploy

Backend MCP relies on your Nhost Auth project being set up as an OAuth2 provider. Complete the authentication prerequisites — the OAuth2 provider, CIMD, and a consent page — before you deploy.

Deploy to Nhost Run

One-click install

Use the one-click install link to create the Run service with sensible defaults:

Deploy MCP to Nhost Run

After clicking the link, edit the environment variables to match your project:

• MCP_AUTH_URL — your project’s auth URL, for example https://SUBDOMAIN.auth.REGION.nhost.run/v1 (or your custom domain).
• MCP_REALM — the public URL where Backend MCP will be reachable.
• MCP_GRAPHQL_ENDPOINT — the GraphQL endpoint Backend MCP forwards requests to.
• MCP_INSTRUCTIONS — instructions that help the assistant understand your application.
• MCP_ENFORCE_ROLE — the role to enforce (for example user_mcp), or remove it to accept any role.

run-mcp.toml

Add a run-mcp.toml file to your project directory:

name = 'mcp'
command = ['mcp']

[image]
image = 'nhost/mcp:0.1.0'

[[environment]]
name = 'MCP_AUTH_URL'
value = 'https://SUBDOMAIN.auth.REGION.nhost.run/v1'

[[environment]]
name = 'MCP_REALM'
value = 'https://mcp.acme.com'

[[environment]]
name = 'MCP_GRAPHQL_ENDPOINT'
value = 'http://hasura-service:8080/v1/graphql'

[[environment]]
name = 'MCP_INSTRUCTIONS'
value = 'This MCP server interacts with my application'

[[environment]]
name = 'MCP_ENFORCE_ROLE'
value = 'user_mcp'

[[ports]]
port = 3000
type = 'http'
publish = true

[resources]
replicas = 1

[resources.compute]
cpu = 125
memory = 256

Then deploy Backend MCP:

nhost run config-deploy \
  --config run-mcp.toml \
  --service-id $SERVICE_ID

Once deployed, Backend MCP is reachable at its published port and any MCP-compatible client can connect. See Connecting clients.

Run locally

To try Backend MCP against a local project, run it as part of your local stack:

nhost up --run-service run-mcp.toml

Point MCP_AUTH_URL and MCP_GRAPHQL_ENDPOINT at your local endpoints (for example https://local.auth.local.nhost.run/v1).

Configuration reference

Every setting can be supplied as a flag or an environment variable. MCP_GRAPHQL_ENDPOINT and MCP_AUTH_URL are required. See Configuration for the full list.