MCP Server Integration With Self-Hosted Agent Frameworks
Self-hosted MCP servers require deliberate choices about transport, authentication.

Integrating MCP servers with self-hosted agent frameworks requires deliberate choices about transport and discovery, authentication and credential handling, and state persistence. For persistent AI agent infrastructure versus serverless functions, the decisive distinction is what survives between calls and sessions. A cold-started function needs an agent’s working files, acquired credentials, and memory to be restored, while persistent infrastructure takes care of that below application code.
Why self-hosting MCP servers is an architectural decision, not just an ops preference
A SaaS gateway places tool invocations, credentials, and agent context outside the organization’s network. For organizations whose data residency requirements or internal security policies forbid that movement, where the service runs can rule out most managed MCP gateways before they start comparing features. Self-hosting therefore changes more than who operates the service. It makes the organization responsible for how agents reach tools, whose authority each invocation uses, and what survives after a call finishes.
Gateways help with the N×M integration problem because, without them, every agent needs a connection to every tool it uses. MCP reduces that coupling by separating tool capability from agent identity, so a tool server can serve different frameworks through the same protocol. Deployment policy decisions remain in the transport and hosting layers, where a convenient local connection and a shared production service have different requirements.
Transport and discovery: how self-hosted MCP servers actually connect to agents
STDIO is the default for many MCP servers and a low-friction starting point for local development. The agent spawns each server as a subprocess, making the connection fit naturally on one machine. Remote agents need a different route. Once the agent runs elsewhere, the local STDIO server needs a gateway or proxy, and its credentials may still be scattered across developer machines unless credential handling changes too.
SSE, or Server-Sent Events, and Streamable HTTP allow remote server connections. Gateways built for production usually make servers available through one of these transports so agents on different hosts can reach them. Neither transport settles discovery by itself. Agents still need a deterministic account of which servers are available and which tools those servers expose, rather than an assumption that a reachable endpoint contains the right capabilities.
Stacklok’s ToolHive runs each MCP server in an isolated container, and its Kubernetes Operator provides a Virtual MCP Server, or vMCP, gateway endpoint. Agents connect to that endpoint rather than to each server individually, consolidating multi-server discovery. Nango takes a different approach to the exposed toolset. Its built-in MCP server serves deployed or catalog-selected tools at a fixed endpoint with typed schemas, giving agents a curated set rather than every endpoint a public server might expose. Docker MCP Gateway supports STDIO, SSE, and streaming HTTP transports while placing servers in separate containers with configurable resource limits and signed images.
The official Python SDK’s FastMCP interface makes the underlying tool implementation comparatively small. It takes care of discovery, generates the argument schema, and formats the response automatically, so the developer only has to write each tool’s logic. Hosting remains the larger integration task. With no central registry to show which tools are good, virtual servers and typed tool manifests give developers ways to set what an agent can discover. They make the available toolset explicit, but do not establish whether a caller should be allowed to use it.
Authentication and credential handling at the self-hosted layer
Authentication begins where discovery stops, by establishing who is calling and which downstream account that caller may use. Most STDIO-based MCP servers have no authentication, while credentials may be hardcoded or distributed across developer machines. Local access to a subprocess is not a substitute for per-request identity in a service acting for multiple customers.
Stripe’s remote MCP server uses OAuth-based client access, which works for an operator who connects their own account. That does not resolve customer-by-customer access to Salesforce or Slack. Each customer needs an authorized connection to their own account, and the agent’s access must remain tied to that customer.
Nango implements this separation through customer authorization under the developer’s brand, server-side token storage, and automatic refresh. The agent receives a connection ID, while the raw credential stays server-side. Arcade.dev uses per-user OAuth, checks permissions before a tool runs, and has an open-source framework for custom MCP servers that use the same model. For enterprise identity, ToolHive’s embedded authorization server, available as of February 2026, handles OAuth in-process through Okta, Entra ID, or Google. This removes locally stored credentials and a vendor-hosted authorization endpoint from the critical path.
Authorization does not establish that the tool itself is trustworthy. In September 2025, the postmark-mcp npm package shipped an update that sent a hidden copy of every email it sent to an attacker’s address. The incident places software provenance in the same security discussion as tokens, because a correctly authorized invocation can still execute compromised code. For tools touching customer data, the lesson is to pair signed images and provenance attestation with per-request identity, while keeping authorization in-process for a truly self-hosted deployment.
State persistence across tool calls: the layer that makes agents actually work
A lookup can work without keeping anything after the response, but a multi-step agent needs to carry work from one call to the next. Files, credentials, and partially completed work may all need to survive from one invocation to another. Authentication alone cannot provide that continuity. An agent that receives permission to execute a tool still needs access to the work on which its next authorized call depends.
Short-term persistence keeps a result from one step so it can be used later in the same task. If tool call N produces something needed by tool call N+3, a stateless gateway requires that state to be serialized elsewhere or reconstructed. Session resumption raises a broader requirement. An agent returning hours or days later may need its working directory, acquired credentials, and memory, none of which a cold-started serverless function retains on its own.
This is the relevant limitation when considering serverless functions such as Cloud Run for long-running agents. Successful execution of an MCP call does not provide durable working state for the next invocation or resumed session. A function-based design must arrange that continuity outside the individual execution. Without it, a sequence of successful calls can still fail to complete a task that depends on earlier work.
Frameworks address persistence at the workflow or agent level. Mastra provides workflows for durable execution and state management, while LangGraph maintains state across nodes in a graph-based workflow. Both fit multi-step tool sequences. Letta addresses longer-term memory through stateful agents and a TypeScript agent harness and App Server in Letta Code. These abstractions help with durable execution, but workflow-level persistence still leaves the developer to handle serialization instead of keeping the whole working environment intact.
Isolated VMs with persistent disks preserve files, credentials, and installed packages across sleep and redeploy without explicit application-level serialization and restoration of those assets. Snapshot-restore scheduling makes idle periods a storage cost rather than an idle-compute cost, with wake latency low enough not to become a user-facing problem. Container isolation serves a different purpose. Docker’s gateway and ToolHive isolate MCP servers, but that isolation does not itself preserve an agent’s state across calls or sessions.
How the three layers interact: a concrete integration path for a self-hosted agent
MCP servers behind ToolHive’s vMCP gateway on Kubernetes give the agent a consolidated remote endpoint, while a typed-endpoint server such as Nango defines a curated toolset. In either path, HTTPS replaces local STDIO for the agent’s tool access. The deployment still needs a credential model appropriate to the users on whose behalf those tools run.
The next decision binds each request to a user’s authorized connection. In-process OAuth and per-user token storage keep credentials server-side, while automatic refresh means the agent has no raw tokens to manage. Enterprise deployments can federate through Okta or Entra ID without a vendor-hosted authorization endpoint. These are deployment requirements. An endpoint may still lack authentication features the deployment needs, and all the parts put together have to use the same trust boundary.
Mastra or LangGraph can provide a workflow abstraction for session-scoped intermediate state, while VM-level persistence fits agents whose files, installed packages, and memory must survive across sessions. This choice also clarifies credential handling. An agent’s environment can be kept without giving it downstream tokens, so durable state can keep credentials server-side. At the same time, secure token storage cannot bring back missing files or partially completed work.
Tool execution logs, authentication events, and state checkpoints need to reach the same observability stack. ToolHive aligns with OTel MCP semantic conventions, merged January 2026, so traces and metrics use standard attribute names compatible with Grafana, Datadog, and similar tooling. The EU AI Act’s staged applicability through 2026, 2027, and into 2028 adds a concrete compliance consideration, although a self-hosted transport choice alone does not establish compliance.
Choosing a gateway or running without one: what each option actually trades away
Running without a gateway is appropriate when the agent and tools share a trusted machine and there are no multi-tenant or data-residency constraints. Direct STDIO or a basic HTTP server can work in that setting. Sharing changes the requirements. A self-hosted gateway adds operational work in exchange for organizational control over the route tool calls take, the identity checks applied to them, and the provenance controls around deployed servers.
ToolHive combines an Apache 2.0 license, supply-chain attestation, and embedded authorization with a Kubernetes Operator for cluster deployments. Its CLI and Desktop UI also support local use, but the full enterprise feature set assumes cluster ownership and Kubernetes expertise. Docker’s gateway offers a narrower operating model. It provides container-native deployment, signed images, multiple transports, and an MIT license, but container isolation is not a complete governance stack, and identity and policy controls are more limited.
Obot has a gateway, catalog, chat client, and server hosting together in one Kubernetes-native deployment. That breadth reduces the number of separately assembled components, while its newer position leaves production maturity less established than the other options. Nango concentrates on a different boundary. Its open-source offering combines white-label per-user authentication, custom typed tools, a built-in MCP server, and observability, while data syncs and webhooks remain a separate concern. Bifrost by Maxim AI emphasizes low gateway overhead and semantic caching to reduce token costs, although governance and auditability can outweigh microsecond-level latency differences in production selection.
How well these choices work with the framework affects their cost. Mastra provides an ergonomic MCP path for TypeScript teams, while Python teams can choose among AutoGen, PraisonAI, LangGraph, and Letta with differing native MCP support and state management. Agents needing a working environment preserved between wakes require compute that preserves disk, memory, and installed state, or application-managed restoration of the state they need. The decision framework is therefore to identify the required network boundary, per-request identity, and persistence scope before accepting a gateway’s defaults. Complexity is justified only where one of those requirements demands it.


