How does it work

What is How does it work?

Pomerium Chat is a minimal chat application that demonstrates how to secure remote Model Context Protocol (MCP) servers with Pomerium. It integrates MCP clients (like Claude.ai or OpenAI) with internal MCP servers behind Pomerium’s authentication and authorization gateway, and is intended for developers building agentic frameworks or internal apps that invoke MCP servers.

How to use How does it work?

Set up the required environment variables in .env-mcp-app-demo (an OpenAI API key), configure Pomerium routes in pomerium-config.yaml with your domain, and run docker compose up -d. The demo includes a SQLite MCP server. After signing in at https://mcp-app-demo.YOUR-DOMAIN/, you can query the database via natural language.

Key features of How does it work

• Secures local HTTP MCP servers with Pomerium’s OAuth 2.1 gateway
• Supports upstream OAuth flows for services like GitHub or Google Drive
• External clients never see upstream OAuth tokens (TI)
• MCP servers can remain stateless and token‑free
• Provides an endpoint to list available MCP servers and their connection status
• Allows redirecting users to complete upstream OAuth authentication

Use cases of How does it work

• Exposing an internal database MCP server to remote MCP clients like Claude.ai
• Building internal applications that call MCP servers via LLM APIs (OpenAI, Claude)
• Secure proxying of MCP requests that require upstream OAuth tokens

FAQ from How does it work

What are the prerequisites for running the demo?

You need a Linux or macOS host, Docker and Docker Compose, port 443 exposed to the internet for Let’s Encrypt TLS, and an OpenAI API key.

How does Pomerium handle authentication for MCP servers?

Pomerium sits between MCP clients and servers, managing sign‑in via its own interface. It issues an External Token (TE) to the client and, if needed, obtains an Internal Token (TI) from an upstream OAuth provider – the client never sees TI.

What is the difference between External Token (TE) and Internal Token (TI)?

TE is an externally‑facing token from Pomerium used by clients to authenticate requests to MCP servers. TI is an internal token that Pomerium obtains from an upstream OAuth provider and passes to the MCP server when proxying requests.

How do I make an MCP server accessible to an external client?

Configure a Pomerium route with the mcp property (e.g., mcp: server: {}) pointing to the internal MCP server. Pomerium then handles authentication and authorization for all incoming requests.

How can my own application obtain an External Token for an MCP server?

Enable mcp.pass_upstream_access_token on your app’s route. Pomerium will supply the backend with an Authorization header containing the External Token, which can then be forwarded to LLM APIs or agentic frameworks.