pomerium/mcp-app-demo

https://github.com/user-attachments/assets/50a17106-a471-4f64-be81-982c09d4689e
## Pre-requisites
1. Linux or MacOS host
2. Docker and Docker Compose
3. Your machine should have port 443 exposed to the internet so that it could acquire TLS certificates from LetsEncrypt and OpenAI could call your MCP server endpoints.
4. OpenAI API Key
## Quickstart
### Environment Variables
Create a .env-mcp-app-demo file in the root directory and add the following environment variables:
bash
OPENAI_API_KEY=your_api_key_here
### Pomerium Config
Update pomerium-config.yaml and replace YOUR-DOMAIN with the subdomain you control. Create A DNS records for relevant hosts (or .YOUR-DOMAIN).
By default, the access policy limits access to users with emails in YOUR-DOMAIN. See policy language reference if you need to adjust it.
### Docker Compose
See docker-compose.yaml file in this repo.
bash
docker compose up -d
It includes a demo SQLite server that requires a demo database, for example https://github.com/jpwhite3/northwind-SQLite3 that needs be saved as sqlite.db.
### Testing
Now you should be able to navigate to https://mcp-app-demo.YOUR-DOMAIN/.
A sign-in page would open. After you signed in, you should be redirected to the application itself.
There should be a demo database server (Database) acessible and in Connected status. Click on it to use it in the conversation.
Now you may ask some questions like "What were our sales by year", and see how OpenAI large language model inference would interact with the MCP database server running on your computer to obtain the answers.
# How does it work
See Model Context Protocol Capability Overview for more details.
## Token Vocabulary
External Token (TE):
An externally-facing token issued by Pomerium that represents the user's session. This token is used by external clients (such as Claude.ai, OpenAI, or your own apps) to authenticate requests to Pomerium-protected MCP servers.
Example: The token you provide to an LLM API or agentic framework to allow it to call your MCP server.
Internal Token (TI):
An internal authentication token that Pomerium obtains from an upstream OAuth2 provider (such as Notion, Google Drive, GitHub, etc.) on behalf of the user. This token is never exposed to external clients. Pomerium uses this token to authenticate requests to the upstream service when proxying requests to your MCP server.
Pomerium acts as a secure gateway between Model Context Protocol (MCP) clients and servers. It provides authentication and authorization for local HTTP MCP servers, using OAuth 2.1 flows. This setup is especially useful when your MCP server needs to access upstream APIs that require OAuth tokens (such as Notion, Google Drive, GitHub, etc.).
It also enables you to build internal applications that use agentic frameworks or LLM APIs capable of invoking MCP servers, as demonstrated in this repository.
To understand this setup, let's look at how an MCP client communicates with MCP servers that are protected by Pomerium.
## 1. Exposing an Internal MCP Server to a Remote Client
https://github.com/user-attachments/assets/c7a809ad-6f0a-4ea3-94a2-6cf22ea6d27b
Suppose you want to allow an external MCP client (like Claude.ai) to access your internal MCP server, but you want to keep it secure. Pomerium sits in front of your server and manages authentication and authorization for all incoming requests.