Sync open source content 🐝 (from b7263efd7ed37b767fba078a1f59ac61a950f9ad)

Author: beezythebot

docs/ai-control-plane/distribute/mcp-servers/authentication/index.mdx

@@ -47,11 +47,11 @@ Public visibility skips authentication entirely: any caller reaches the server w
   A public server still uses its own credentials. Attached system environment variables and configured upstream headers are sent on every call, including calls from anonymous users. Public means anonymous callers get to spend those credentials, not that the credentials are withheld.
 </Callout>
 
-## Legacy models
+## External servers
 
-Two older authentication models remain live for toolset-backed servers created before user sessions shipped:
+Two guides cover OAuth against an authorization server outside the Control Plane, on toolset-backed servers:
 
-- [Secure an MCP server with OAuth](/docs/ai-control-plane/distribute/mcp-servers/secure-with-oauth) covers the hosted OAuth proxy, where the platform fronts an upstream provider.
+- [Secure an MCP server with OAuth](/docs/ai-control-plane/distribute/mcp-servers/secure-with-oauth) covers the OAuth credential styles those servers accept: pre-obtained access tokens, the client credentials flow, and several security schemes in one OpenAPI document.
 - [Build MCP with external OAuth](/docs/ai-control-plane/distribute/mcp-servers/oauth-external-server) covers pointing clients at a third-party authorization server directly.
 
-New servers should use user sessions. The legacy models advertise OAuth scopes and behave differently around token storage and revocation, so their pages are the reference for servers already on them.
+Both advertise OAuth scopes, and both handle token storage and revocation differently from user sessions.

docs/ai-control-plane/distribute/mcp-servers/index.mdx

@@ -1,78 +1,87 @@
 ---
 title: MCP Servers
-description: "Every MCP server has one backend — remote, tunneled, or built. Pick a backend, then configure auth, visibility, publishing, and team access the same way."
+description: "Every MCP server has exactly one backend: remote, tunneled, or built. The backend decides where the tools come from, and everything above it works the same way."
 ---
 
 import { Callout } from "@/mdx/components";
 
-An MCP server is an addressable endpoint that agents connect to. Each server has exactly one backend, and the backend decides where its tools come from:
+An MCP server is an addressable endpoint that MCP clients connect to. Each server has exactly one backend, and the backend decides where its tools come from.
 
-- **Remote** — the server points at an MCP server someone else runs. The Control Plane registers the URL and proxies whole MCP sessions to it.
-- **Tunneled** — the server points at an MCP server running inside a private network. A tunnel agent dials out to the Control Plane, so the private server gets a hosted URL without any inbound connectivity.
-- **Built** — the Control Plane generates the server itself from a first-party source: an OpenAPI document or a TypeScript functions project.
+Everything layered above the backend works the same way, whichever backend a server uses. Tools, authentication, upstream credentials, visibility, custom domains, publishing to collections, team access, and tool logs are properties of the MCP server, not of the thing behind it.
 
-The three are mutually exclusive, and the database enforces it. A server cannot proxy a remote URL and serve built tools at the same time, and the backend is fixed when the server is created.
+## Access requirements
+
+<Callout type="info">
+  Viewing MCP servers requires the `mcp:read` or `mcp:write` scope. Creating a server and editing its settings, visibility, authentication, tool filtering, or team access requires the `mcp:write` scope. Publishing a server to a collection requires the `org:admin` scope. The [default Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions) has full access. The default Member role has `mcp:read`, so Members can view MCP servers but cannot create, edit, or publish them.
+</Callout>
+
+## The server list
+
+The **MCP** page lists every server in the project, in two sections. Open it from **Distribute > MCP** in the dashboard.
+
+**Hosted MCP Servers** lists every source exposed as an MCP server: OpenAPI-backed, functions, catalog servers, and custom remote MCP alike. A card view and a table view are both available, with columns for name, visibility, URL, and tools. Search and filters narrow the list, including a filter for servers included in plugins. **New MCP Server** creates a server.
+
+**Built-in MCP Servers** lists platform-provided servers such as **MCP Logs**. Any MCP client can connect to these.
 
-Everything layered above the backend works the same either way. Authentication, upstream credentials, visibility, custom domains, publishing to collections, team access, and tool logs are all properties of the MCP server, not of the thing behind it.
+Opening a server shows its detail page. The sidebar carries the MCP URL with a copy button and a link to the hosted installation page, which lists per-client setup instructions. For client-specific walkthroughs, see the [setup guides](/docs/ai-control-plane/guides).
 
 ## Choosing a backend
 
+**New MCP Server** asks for a backend first:
+
+- **Remote** — the server points at an MCP server that someone else runs. The Control Plane registers the URL and proxies whole MCP sessions to it.
+- **Tunneled** — the server points at an MCP server that runs inside a private network. A tunnel agent dials out to the Control Plane, so the private server gets a hosted URL without any inbound connectivity.
+- **Built** — the Control Plane generates the server itself from a first-party source: an OpenAPI document or a TypeScript Functions project.
+
+The three are mutually exclusive, and the database enforces it. A server cannot proxy a remote URL and serve built tools at the same time, and the backend is fixed when the server is created.
+
 | Situation | Backend | Start here |
 | --- | --- | --- |
 | A vendor already runs an MCP server and it needs governance, auth, and logging | Remote | [Remote MCP servers](/docs/ai-control-plane/distribute/mcp-servers/remote-servers) |
 | An MCP server already exists but runs behind a firewall or inside a VPC | Tunneled | [Tunneled MCP servers](/docs/ai-control-plane/distribute/mcp-servers/tunneling) |
 | No MCP server exists yet, but an OpenAPI document or a TypeScript codebase does | Built | [Building MCP servers](/docs/ai-control-plane/distribute/mcp-servers/building-servers) |
 
-Two follow-on questions apply to every server regardless of backend. [How tools appear on a server](/docs/ai-control-plane/distribute/mcp-servers/tool-discovery) covers where the tool list comes from and which tool-shaping features apply to which backend. [Authentication](/docs/ai-control-plane/distribute/mcp-servers/authentication) covers who may call a server and which credential the server uses upstream.
+## Tools on a server
 
-## Access requirements
+The **Tools** tab curates exactly which tools a server exposes.
 
-<Callout type="info">
-  Viewing this page requires the `mcp:read` or `mcp:write` scope. Creating a server with **New MCP Server** and editing settings, visibility, auth, tool filtering, or team access require the `mcp:write` scope, and publishing a server to a collection requires the `org:admin` scope. Full access is included in the [default Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions); the default Member role includes `mcp:read`, so Members can view MCP server pages but cannot create, edit, or publish.
-</Callout>
+Where that tool list comes from depends on the backend, and the two answers are opposites. Built servers capture their tool list once per deployment. Remote and tunneled servers proxy `tools/list` live. The difference decides how changes propagate and which tool-shaping features apply to which backend, so [How tools appear on a server](/docs/ai-control-plane/distribute/mcp-servers/tool-discovery) covers it in full.
 
-## Server list
+[Tag-based tool filtering](/docs/ai-control-plane/distribute/mcp-servers/tool-filtering) shapes what a client sees. It lets a client connect to a focused subset of the tools on a server by selecting tags at install time.
 
-The **MCP** page lists every server in the project. Open it from **Distribute > MCP** in the dashboard.
+The **Resources** and **Prompts** tabs hold the other MCP capabilities a server serves.
 
-The **Hosted MCP Servers** section lists every source exposed as an MCP server — OpenAPI-backed, functions, catalog servers, and custom remote MCP alike. View as cards or a table (columns: name, visibility, URL, tools), search, filter (including servers included in plugins), and create servers with **New MCP Server**.
+## Authentication
 
-A **Built-in MCP Servers** section lists platform-provided servers, such as **MCP Logs**, ready to connect from any MCP client.
+Authentication answers two questions that are configured independently and are easy to confuse:
 
-## Server detail
+- **Who is calling this MCP server?** [User sessions](/docs/ai-control-plane/distribute/mcp-servers/authentication/user-sessions) answer this. The Control Plane acts as the authorization server and issues tokens to MCP clients.
+- **Which credential does the server use upstream?** [Upstream credentials](/docs/ai-control-plane/distribute/mcp-servers/authentication/upstream-credentials) answer this, either per end user through remote identity providers, or with one shared credential for every caller.
 
-Each server's detail page carries the connection surface and full configuration, in tabs:
+The **Authentication** tab configures both. See [Authentication](/docs/ai-control-plane/distribute/mcp-servers/authentication) for how the two fit together.
 
-- **Overview** — tool calls, failed calls, error rate, and average latency versus the previous period, tool call trends, top tools by calls and by failure rate, and top users
-- **Tools** — curate exactly which tools the server exposes, with tag-based filtering
-- **Resources** and **Prompts** — additional MCP capabilities the server serves
-- **Authentication** — configure who may call the server and which credential it uses upstream
-- **Team Access** — see below
-- **Settings** — see below
+A toolset-backed server can also authenticate against an authorization server outside the Control Plane. [Secure with OAuth](/docs/ai-control-plane/distribute/mcp-servers/secure-with-oauth) covers the OAuth credential styles those servers accept, and [Build MCP with external OAuth](/docs/ai-control-plane/distribute/mcp-servers/oauth-external-server) covers pointing clients at a third-party authorization server.
 
-The sidebar shows the server's MCP URL with a copy button and a link to its hosted installation page, which lists per-client setup instructions. For client-specific walkthroughs, see the [setup guides](/docs/ai-control-plane/guides).
+## Distribution
 
-## Settings: visibility, publishing, and domains
+The **Settings** tab controls how a server reaches the people who use it:
 
-The **Settings** tab controls how the server is distributed:
-
-- **Visibility** — disabled, private, or public. A private server requires an authenticated caller. A public server accepts anonymous callers and is only available on a tunneled backend, and only after the tunnel source owner opts in.
-- **Custom Slug** and **Custom Domain** — control the server's URL
-- **Server Instructions** — the instructions returned to LLMs when they connect
-- **Publishing** — organization admins publish servers to collections so others in the organization can discover and install them
-- **Export JSON** — export the MCP configuration
-- A danger zone for disabling or deleting the server
+- **Visibility** — disabled, private, or public. A private server requires an authenticated caller. A public server accepts anonymous callers, and public visibility is available only on a tunneled backend, and only after the tunnel source owner opts in.
+- **Custom Slug** and **Custom Domain** — control the URL of the server
+- **Publishing** — organization admins publish servers to collections, so others in the organization can discover and install them
 
 <Callout type="warning">
   Making a server public does not strip its credentials. A public server still serves its attached system environment variables and upstream headers on every call, which means anonymous callers spend the same API keys an authenticated caller would. See [Upstream credentials](/docs/ai-control-plane/distribute/mcp-servers/authentication/upstream-credentials).
 </Callout>
 
-## Team Access
+The **Settings** tab also holds **Server Instructions**, the instructions returned to LLMs when they connect, an **Export JSON** action for the MCP configuration, and a danger zone for disabling or deleting the server.
+
+## Team access
 
-The **Team Access** tab shows who can use the server: every member with their role and read, write, and connect access levels. Access derives from role grants scoped to the server — down to individual tools, where a member's badge opens the exact tool list they can use. Roles are configured in the organization's roles and permissions settings.
+The **Team Access** tab shows who can use the server: every member with their role and read, write, and connect access levels. Access derives from role grants scoped to the server, down to individual tools, where a member's badge opens the exact tool list they can use. Roles are configured in the roles and permissions settings for the organization.
 
-## Tunneled MCP servers
+## Monitoring
 
-Tunneled MCP servers expose an MCP server that runs inside a private network, with no inbound connectivity, through the platform. A lightweight tunnel agent runs next to the private server and opens a single outbound connection to the platform's tunnel gateway. MCP traffic is relayed back over that connection, so nothing in the private network is exposed directly.
+The **Overview** tab reports tool calls, failed calls, error rate, and average latency against the previous period. It also charts tool call trends, ranks top tools by calls and by failure rate, and lists top users.
 
-See [Tunneled MCP servers](/docs/ai-control-plane/distribute/mcp-servers/tunneling) for setup, per-plan limits, key rotation, and public visibility.
+[Tool logs](/docs/ai-control-plane/observe/tool-logs) records the individual calls behind those numbers, across every server in the project.

docs/ai-control-plane/distribute/mcp-servers/oauth-external-server.mdx

@@ -325,7 +325,7 @@ Now we'll configure Speakeasy to work with our external OAuth server. After uplo
 You'll need to make your toolset public to use OAuth.
 :::
 
-In the OAuth configuration page, choose **External Server** instead of OAuth Proxy and enter the server slug as well as the metadata for your OAuth server.
+In the OAuth configuration page, choose **External Server** and enter the server slug as well as the metadata for your OAuth server.
 
 ![Speakeasy OAuth Server Configuration](/assets/docs/gram/img/guides/oauth-external-server/gram-oauth-server-config.png)
 

docs/ai-control-plane/distribute/mcp-servers/secure-with-oauth.mdx

@@ -59,7 +59,7 @@ Before implementing OAuth, consider what kind of credentials you expect end user
 - **What users provide**: Nothing initially - they authenticate interactively
 - **How it works**: Dynamic OAuth flow when the MCP server is accessed
 - **Best for**: Public-facing servers requiring user consent with external OAuth providers
-- **Complexity**: High - requires DCR implementation or OAuth proxy
+- **Complexity**: High - requires DCR implementation
 
 **Speakeasy can integrate OAuth into a server in any way that's currently possible within the MCP context.** The key is choosing the approach that best fits your existing authentication system and user experience goals.
 
@@ -93,7 +93,7 @@ Placing Managed OAuth in front of a server is a Pro and Enterprise feature.
 
 An MCP Server must be marked `public` to attach Managed OAuth in front of it.
 
-Please [book in time with our team](https://calendly.com/sagar-speakeasy/30min) for white-glove service with proxy setup or DCR compliance. We'll get you up and running.
+Please [book in time with our team](https://calendly.com/sagar-speakeasy/30min) for white-glove service with DCR compliance. We'll get you up and running.
 </Callout>
 
 
@@ -221,7 +221,7 @@ When implementing authentication for your MCP server, remember:
    - Access tokens: Simple, works with existing systems
    - Client credentials: Good for server-to-server auth
    - Speakeasy OAuth: Organization-based access control for private servers (no external OAuth needed)
-   - User-facing OAuth: Best for public servers with external OAuth providers (requires DCR or proxy)
+   - User-facing OAuth: Best for public servers with external OAuth providers (requires DCR)
 4. **DCR is only needed** if you want MCP clients to handle OAuth flows with external providers directly, but it is a requirement for that scenario
 5. **We can help** with white-glove service for guiding towards DCR compliance