Skip to main content

Grant MCP servers and profiles to a project

Enterprise Tier

A project controls which Model Context Protocol (MCP) servers it can use and exposes them to AI clients through MCP profiles. Scoped to a project, MCP falls under the same isolation as models: a project sees only its own servers, and its profiles are reachable only with its own keys, on the endpoints of the data planes labelled with it.

An MCP server exposes a tool or data source to AI clients; an MCP profile aggregates one or more servers behind a single endpoint that clients connect to once.

Persona: Platform operator or project administrator working in the Admin Console.

Estimated time: 15 to 25 minutes for the first profile.

Outcomes​

By the end of this guide:

  • The MCP servers a project may use are granted to it.
  • A profile that bundles the chosen servers is published on every endpoint that serves the project.
  • The profile's isolation is understood: it is reachable only with the project's key, including on a hostname that serves other projects.

Prerequisites​

  • The project MCP permission on the project, held by the Project Owner and Super Admin roles. From 0.8.0, listing, adding, and removing a project's MCP servers needs this permission, and the MCP Admin role does not include it: an MCP Admin who manages a project's servers also needs Project Owner on that project, or Super Admin. A Viewer can list the project's servers but not add or remove them.
  • At least one data plane labelled with the project, so the profile has an endpoint. See Serve a project from a data plane.
  • The MCP servers available in the organization's catalog. Cataloging and governing servers is covered in Govern MCP server access.

Step 1: grant MCP servers to the project​

  1. Use the project switcher to select the project.
  2. Open MCP Servers and enable the servers this project may use.

A project can see and use only the servers granted to it. A server that is not granted is neither listed for the project nor callable through it, which is what keeps one project's tools separate from another's.

Grant servers through the API​

The same grants are made through the admin API. From 0.8.0:

  • ListProjectMcpServerCandidates returns the enabled catalog servers the project does not have yet, ordered by name, with a case-insensitive name search. A page holds 50 servers by default and at most 200 (page_size); the response's next_page_token, sent back as page_token, fetches the next page and is empty on the last. It needs the same permission as adding a server.
  • AddProjectMcpServer and RemoveProjectMcpServer grant and withdraw a server.
  • ListProjectMcpServers returns each granted server's name, description, icon, enabled state, and last update, including servers disabled in the catalog since they were granted. It takes a page (50 servers by default, 200 at most, sorted by server_id, name, updated_at, or is_enabled), a name search, and an enabled filter, and reports the total of matching servers. A request that sets none of these returns every server in one response, as before 0.8.0.

Step 2: build an MCP profile​

A profile bundles one or more of the project's granted servers into a single endpoint an MCP client connects to.

  1. In the project, open My MCP Profiles and select Add MCP Profile, then name it.
  2. Select Add Server, choose from the servers granted to the project, and enable the tools wanted from each.
  3. Set the profile's authentication, either API key or OAuth.

The profile is published at a path on every hostname declared by a data plane labelled with the project. Securing MCP credentials and identity is covered in Secure MCP secrets and identity.

Step 3: confirm profile isolation​

The profile inherits the project's isolation.

  • It is reachable only on hostnames whose data planes serve the project. Called on a hostname whose data plane does not serve the project, the path is not served and returns 404.
  • It accepts only the project's keys. A key from another project is refused with 403.
  • On a data plane on 0.7.0 or later that serves several projects on one hostname, each project sees only its own MCP servers and profiles on that hostname; one project's profiles never replace another's.

The developer-side workflow of connecting a client such as Claude Code, Cursor, or an MCP-capable editor to the profile URL is covered in Aggregate MCP servers into a profile.

Where to go next

Govern MCP server access

The organization-wide catalog and controls behind per-project grants.

Aggregate MCP servers into a profile

The developer-side view of connecting a client to a profile.

Secure MCP secrets and identity

How profile credentials and identity are protected.