# MCP Gateway concepts This page defines the objects the MCP Gateway works with and how they relate. For the request path every call follows through the gateway, and how the gateway fits with identity, security, and observability, see [How the MCP gateway works](/docs/ai-control-plane/concepts#how-the-mcp-gateway-works). ## MCP servers An MCP server is an address that MCP clients connect to. Each server is one source of tools. Authentication, upstream credentials, visibility, custom addresses, team access, and tool logs belong to the MCP server, not to the system behind it. Those settings work the same way whatever the server's type. [Managing an MCP server](/docs/ai-control-plane/mcp-gateway/managing-servers) walks through them tab by tab. ## Server types Every server is one of three types, fixed when the server is created: - **Remote**: an MCP server someone else runs, added by its URL or from the [MCP Catalog](/docs/ai-control-plane/mcp-gateway/catalog). The gateway proxies whole MCP sessions to it. See [Remote MCP servers](/docs/ai-control-plane/mcp-gateway/remote-servers). - **Tunneled**: an MCP server inside a private network. A tunnel agent dials out to the platform, so the server gets a URL without any inbound connectivity. Tunneling is enabled per organization. See [Tunneled MCP servers](/docs/ai-control-plane/mcp-gateway/tunneled-servers). - **Hosted**: Speakeasy hosts the server, generated from an OpenAPI document or TypeScript functions. Uploading an OpenAPI document creates a hosted server automatically. A function becomes a server through **Build a server** on its [source](/docs/ai-control-plane/mcp-gateway/building-servers/sources). Functions are enabled per organization. See [Building MCP servers](/docs/ai-control-plane/mcp-gateway/building-servers). A server cannot change type, and it cannot proxy a remote URL and serve hosted tools at the same time. To combine servers of different types, use a gateway endpoint. ## Gateway endpoints A [gateway endpoint](/docs/ai-control-plane/mcp-gateway/gateway-endpoints) puts several MCP servers, of any mix of types, behind one address, one sign-in, and one consent screen. The [organization gateway](/docs/ai-control-plane/mcp-gateway/organization-gateway) is one such URL for the whole organization, reaching every server a person has access to. For when to use each, see [Connecting agents to a gateway](/docs/ai-control-plane/mcp-gateway#connecting-agents-to-a-gateway). ## Plugins and skills A [skill](/docs/ai-control-plane/mcp-gateway/skills) packages instructions an agent loads. The platform records every version of a skill, with diffs. A [plugin](/docs/ai-control-plane/mcp-gateway/plugins) bundles MCP servers and skills, is assigned to roles, and is published to agent marketplaces such as Claude Code, Cursor, and Codex. Skills reach agents only by being bundled into plugins. ## Device agent Gateway controls apply only when an AI tool sends its MCP traffic through the gateway. A developer who adds a server URL by hand, or a tool update that resets its settings, can bypass the gateway entirely. The [device agent](/docs/ai-control-plane/reference/device-agent) closes that gap on developer machines and cloud coding sandboxes. The device agent works with the gateway in four ways: - **Delivers plugins.** The agent renders the organization's plugins and MCP servers into the native configuration of Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, OpenClaw, and Pi. Which plugins reach a device follows each plugin's [assignments](/docs/ai-control-plane/mcp-gateway/plugins#assignments). Entries the user added are left alone. - **Keeps configuration in place.** The agent re-fetches and re-applies policy every 60 seconds by default, so gateway-routed servers survive tool updates, settings resets, and account switches. - **Routes access requests.** When a policy blocks an unapproved MCP server, the developer gets a desktop notification that offers to file an access request. The request lands in the [access review](/docs/ai-control-plane/secure/shadow-mcp/access-review) queue. - **Links to the organization gateway.** The menu bar app links to the [organization gateway](/docs/ai-control-plane/mcp-gateway/organization-gateway), one URL for every server a person has access to. The device agent is in beta and enabled per organization. For deployment through MDM and the other things the agent does, such as telemetry wiring and Shadow AI discovery, see [Device agent](/docs/ai-control-plane/concepts#device-agent) in the AI Control Plane concepts. ## Environments An [environment](/docs/ai-control-plane/mcp-gateway/environments) is a reusable set of configuration and secrets shared across MCP servers. Sensitive values stay masked and centralized instead of living in each client configuration. Each project starts with an environment named Default. ## Tools A tool is one action an agent can call through a server. How a server gets its tools depends on its type. ### Tool definitions A hosted server's tools start as tool definitions. When a [source](/docs/ai-control-plane/mcp-gateway/building-servers/sources) such as an OpenAPI document or a function is uploaded, a [deployment](/docs/ai-control-plane/mcp-gateway/building-servers/deployments) processes it and converts it into tool definitions. For an OpenAPI document, that is every operation in the document. For a function, it is every tool declared in the function manifest. The following image shows a source being processed into tool definitions: ![Generating tools](/assets/docs/ai-control-plane/img/concepts/tool-definitions/tools-generation.png) A tool definition holds both the metadata that describes the tool to an LLM and the configuration the platform uses to execute it, such as how to construct the HTTP request to an API. To build and send that request, the platform combines the tool definition with the server's selected [environment](/docs/ai-control-plane/mcp-gateway/environments). ### Captured per deployment or listed live Hosted servers and proxied servers get their tools in opposite ways: - A **hosted** server captures its tool list once per deployment. Its **Tools** tab curates exactly which tools it exposes, alongside the resources and prompts it serves. - A **remote or tunneled** server proxies `tools/list` live. Its **Inspect** tab connects to the server to list the tools it advertises. The difference decides how tool changes propagate and which features apply to which server type. See [Tool discovery](/docs/ai-control-plane/mcp-gateway/tool-discovery). ### Tool variations and recorded metadata Tool metadata can be overridden without changing the source, in two ways that match the two discovery paths: - A **tool variation** overrides a hosted tool's name, description, tags, annotations, or confirmation prompt. Variations edit stored tool definitions, so they apply to hosted servers only. They are global: a variation applies to the tool on every MCP server that uses it. See [Curating tools](/docs/ai-control-plane/mcp-gateway/building-servers/curating-tools). - **Recorded tool metadata** stores a title and annotation hints per tool name on a remote or tunneled server, layered over the live tool list. See [Recording tool metadata](/docs/ai-control-plane/mcp-gateway/remote-servers#recording-tool-metadata). ### Choosing which tools a server exposes Giving an LLM access to too many tools can exhaust the context window, which may stop agents from working properly or lead the LLM to choose the wrong tool. Some models also cap the number of tools accepted in a single chat completion call. Start from the specific task an agent should perform, then expose only the tools that task needs. A cohesive, task-focused server makes it much more likely that an agent uses an API correctly. Tools from different sources can be combined on one hosted server, so a server for finding inactive customers and emailing them a coupon might pair a customer lookup tool with an email tool. Scoping servers this way also scopes access. A server for sales exposes a different set of tools than one for support, so each team's agents see only what is relevant to their workflows. Three features refine a selection further: - [Tool variations](/docs/ai-control-plane/mcp-gateway/building-servers/curating-tools) sharpen a tool's name and description so the LLM picks the right tool. - [Tag-based tool filtering](/docs/ai-control-plane/mcp-gateway/building-servers/tool-filtering) lets a client connect to a focused subset of a server's tools by selecting tags at install time. - The [Playground](/docs/ai-control-plane/mcp-gateway/building-servers/playground) tests a selection with natural language prompts before a real client connects. ## Two authentication questions Authentication answers two separate questions, configured independently on each server: - **Who is calling the server?** [User sessions](/docs/ai-control-plane/mcp-gateway/access/user-sessions) answer this. The platform acts as the authorization server and issues tokens to MCP clients. - **Which credential does the server use upstream?** [Upstream credentials](/docs/ai-control-plane/mcp-gateway/access/upstream-credentials) answer this, either per person through [authorization servers](/docs/ai-control-plane/identity/remote-identity-providers) or with one shared credential for every caller. A server can answer one question, both, or neither. See [Access, OAuth, and sessions](/docs/ai-control-plane/mcp-gateway/access) for how the two combine and where each server type configures them. ## Visibility, network access, and team access Three separate controls decide who reaches a server. Each one is set independently, and changing one does not change the others: | Control | Decides | Set from | | --- | --- | --- | | Visibility | Whether the server serves traffic at all, and whether callers must authenticate: **Disabled**, **Private**, or **Public** | The status control on the server page | | Network access | Which routes reach a remote or tunneled server: public URLs, the organization private network, or both | The server **Settings** tab, after [Tailscale](/docs/ai-control-plane/mcp-gateway/private-network-access/tailscale) is connected | | Team access | Which people, roles, agents, and groups may connect, view, or manage the server, and which tools they get | The server **Team Access** tab | A private network route still requires authentication, and a public server still applies its upstream credentials. See [Visibility](/docs/ai-control-plane/mcp-gateway/managing-servers#visibility) and [Team access](/docs/ai-control-plane/mcp-gateway/access/team-access). --- Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.