Transports

Connect MCP servers using Fentaris transports.

Connect upstream MCP servers with high-level transport helpers

This page is kept for older links. The current concepts entrypoint is Servers and transports.

Quick Start

Use stdio(...) for local upstream MCP servers:

import { fentaris, mcp, stdio } from "@fentaris/core";

const proxy = fentaris({
  servers: [
    mcp("filesystem", {
      transport: stdio({
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "./demo-files"],
        stderr: "inherit",
      }),
    }),
  ],
});

Use streamableHttp(...) for native remote MCP HTTP endpoints:

import { fentaris, mcp, streamableHttp } from "@fentaris/core";

const proxy = fentaris({
  servers: [
    mcp("remote", {
      transport: streamableHttp({
        url: "https://mcp.example.com/mcp",
        auth: {
          headers: { "x-tenant": "acme" },
          bearerToken: "service-token",
        },
      }),
    }),
  ],
});

Transport Matrix

Direction	Helper	Use case
Upstream	stdio(...)	Local MCP process over stdin/stdout.
Upstream	streamableHttp(...)	Remote native MCP Streamable HTTP endpoint.
Upstream	SseMcpTransport	Legacy SSE-capable MCP servers.
Upstream	HttpTransport	Compatibility adapter for REST-like /listTools and /callTool endpoints.
Downstream	proxy.start()	Default Streamable HTTP exposure for MCP clients.

Stdio Options

command

Executable to spawn.

args

Arguments passed to the upstream process.

env

Environment variables passed to the upstream process.

stderr

How to handle stderr from the upstream process. Use inherit during local development to see upstream logs.

HTTP-Family Auth

streamableHttp(...) supports static headers, bearer tokens, API keys, and per-user header resolvers.

streamableHttp({
  url: "https://mcp.example.com/mcp",
  auth: {
    resolveHeaders: ({ user }) => ({
      "x-user-id": user.id ?? "anonymous",
      authorization: `Bearer ${user.tokens?.remote ?? ""}`,
    }),
  },
})

OAuth 2.1 Upstreams

Declare auth: oauth() on the server when the upstream runs an OAuth 2.1 flow. Fentaris then discovers the authorization server, registers a client, runs PKCE, refreshes tokens, and keeps one authorization per user.

mcp("linear", {
  transport: streamableHttp({ url: "https://mcp.linear.app/mcp" }),
  auth: oauth(),
})

A caller-supplied access token still works: pass it through a resolver and Fentaris forwards it unchanged. Use oauth() when nobody holds a token yet. See Upstream OAuth 2.1.

Close Cleanly

Close the proxy on shutdown so upstream transports can release processes, sockets, and sessions.

process.on("SIGTERM", async () => {
  await proxy.close();
  process.exit(0);
});

Low-Level API

Transport classes such as StdioTransport, StreamableHttpMcpTransport, SseMcpTransport, and exposure transports remain available for advanced integrations. New application docs should prefer stdio(...), streamableHttp(...), and proxy.start().

Related Documentation

• Servers and transports
• Stdio transport
• Proxy setup