Encore MCP Base

Production TypeScript foundation for private ChatGPT Apps, GPT Actions, OAuth, and upstream OpenID Connect.

Encore MCP Base gives engineering teams one secure service boundary for ChatGPT integration work. It exposes MCP Streamable HTTP for GPT Apps, OpenAPI-backed REST endpoints for GPT Actions, and a private OAuth/OIDC provider that bridges account linking to any upstream OIDC identity provider with authorization, token, and userinfo endpoints.

The runtime service uses TypeScript, Encore, and the Node standard library. The runtime dependency list is intentionally small: encore.dev. Development and verification use TypeScript, Node test runner, and oauth4webapi for independent OAuth client behavior.

Start with the full documentation map at docs/index.md.

Designed For

• GPT builders who need Apps and Actions from one authenticated backend.

• Security owners who need clear audiences, scopes, client records, and external identity proof.

• Operators who need public HTTPS deployment, secret placement, key rotation, and release checks.

• Maintainers who need small code files, protocol-owned tests, and documentation that stays outside runtime code.

Related MCP server: MCP Server

At A Glance

Standards Baseline

The source map for external specifications and platform documents lives in External References.

Runtime Shape

flowchart LR
  Apps["ChatGPT Apps"] --> Mcp["/mcp Streamable HTTP"]
  Apps --> Sse["/sse and /messages"]
  Actions["GPT Actions"] --> Rest["/actions/* REST"]
  Browser["Account linking browser"] --> OAuth["/oauth/*"]
  OAuth --> Idp["Upstream OIDC provider"]
  Mcp --> Tools["MCP tools"]
  Tools --> Capabilities["Shared capabilities"]
  Sse --> Tools
  Rest --> Capabilities
  OAuth --> Store["DynamoDB or local file store and signing keys"]

The main service runtime keeps protocol adapters at the edge. ChatGPT Apps reach MCP transports, GPT Actions reach REST endpoints, account linking reaches OAuth routes, and each path uses shared capability modules where behavior overlaps. OAuth uses the configured upstream OIDC provider and the configured store for client grants, tokens, MCP sessions, rate limits, and production metadata cache entries.

Widget Framework Runtime Shape

flowchart LR
  Apps["ChatGPT Apps"] --> Mcp["/mcp Streamable HTTP"]
  Mcp --> ToolDescriptor["tools/list descriptor with ui://widget URI"]
  ToolDescriptor --> UiResource["resources/read UI HTML template"]
  Mcp --> UiResource
  Mcp --> ToolResult["tools/call result with structuredContent"]
  UiResource --> Iframe["ChatGPT sandbox iframe"]
  ToolResult --> Iframe
  Iframe --> WidgetAssets["/app-ui/* JavaScript and CSS"]
  WidgetAssets --> WidgetRuntime["Widget bridge and feature renderer"]

The widget framework runtime starts when ChatGPT reads a tool descriptor that declares a ui:// widget URI. ChatGPT reads the matching MCP UI resource, calls the render tool, passes structuredContent into the sandbox iframe, and the iframe loads the versioned widget assets from /app-ui/*. Detailed widget implementation guidance lives in MCP Apps UI Resources.

Prerequisites

Quick Start

Install Node.js, npm, and the Encore CLI. Then run the service:

npm install
npm run dev

Use a second terminal for first checks:

curl http://localhost:4000/health
curl http://localhost:4000/.well-known/openid-configuration
curl http://localhost:4000/.well-known/oauth-protected-resource/mcp
curl http://localhost:4000/actions/openapi.json

Export a local Actions schema file:

npm run openapi -- --base-url http://localhost:4000 --out var/actions.openapi.json

Local development supplies local URLs, generated signing keys, development OAuth clients, and a local file store at var/oauth-store.json. Automated tests start a local upstream OIDC provider for real authorization-code flows.

Local Defaults

ChatGPT Setup Values

Use these production URL shapes after deploying the service behind HTTPS:

Use registered client IDs and client secrets from the production client registry. The AWS CDK seed command stores generated ChatGPT client secrets in Systems Manager Parameter Store.

Local development values live in GPT Apps Setup and GPT Actions Setup.

Current Capability Surface

MCP Tools

MCP UI Resources

Widget Framework Assets

Feature widgets add their own versioned /app-ui/* JavaScript and CSS assets. The full asset list is documented in MCP API Reference.

Actions Endpoints

Current Actions operations are read-only and declare x-openai-isConsequential: false.

MCP tools and Actions endpoints are connector adapters. Shared capability modules own reusable behavior such as service health, identity profile shaping, and token session data.

OAuth And Identity

The service acts as the OAuth provider that ChatGPT talks to during account linking. The upstream identity provider supplies the actual signed-in user identity through OIDC.

Core OAuth behavior:

• GET /oauth/authorize validates the ChatGPT authorization request and redirects to the upstream provider.

• GET /oauth/callback consumes the upstream authorization response and creates a service authorization code.

• POST /oauth/token exchanges authorization codes and refresh tokens.

• GET /oauth/userinfo returns the profile bound to the access token.

• GET /oauth/jwks publishes public signing keys.

• Well-known metadata publishes OAuth, OIDC, and protected-resource discovery.

Supported client authentication methods are client_secret_post, client_secret_basic, private_key_jwt, and none for metadata-document public clients. Production clients should use explicit client records with approved redirect URIs, scopes, resources, and authentication methods.

External OIDC providers are first-class. AWS CDK Cognito mode is an optional quick-start upstream provider for deployments that need one.

Security Posture

The service is built as production infrastructure from the first commit.

• Production startup requires public HTTPS URLs, durable storage, explicit origins, registered clients, upstream OIDC settings, signing keys, token lifetimes, and rate limits.

• Access tokens are RS256 JWTs with issuer, subject, audience, expiration, client ID, scopes, and profile claims.

• MCP endpoints require the MCP audience. Actions endpoints require the Actions audience.

• Protected MCP tools, MCP resources, and Actions endpoints enforce scopes at the adapter boundary.

• Query-string bearer tokens are rejected.

• Duplicate authorization headers are rejected.

• Production DynamoDB stores OAuth state, refresh tokens, rate-limit buckets, MCP sessions, and metadata cache entries. Local development uses the file store for OAuth state, refresh tokens, rate-limit buckets, and MCP sessions.

• Authorization codes, refresh tokens, session identifiers, rate-limit subjects, and metadata cache keys are stored as hashes.

• Diagnostics are designed for safe operational signals and secret redaction.

• CORS origins are explicit and wildcard origins are rejected.

Security details live in Security Model, OAuth Provider, and Security Review.

Production Readiness Evidence

Project Layout

The development rule is simple: put shared behavior in one focused module, then expose it through MCP tools and Actions REST adapters.

Verification

Run targeted tests while changing one surface:

node --experimental-strip-types --test --test-concurrency=1 test/mcp/transport-bearer.test.ts

Run the full gate before release:

npm run check

The full gate runs TypeScript typecheck, dependency checks, architecture checks, file-scope checks, test-placement checks, and the full Node test suite.

The test harness uses real service processes, local upstream OIDC servers, OAuth client helpers, raw HTTP checks, SSE helpers, and MCP JSON-RPC helpers. Tests are tied to live functionality and protocol behavior.

Deployment

Production deployment can run through the AWS CDK project in ci/cdk/.

The CDK path provisions:

• EC2 on Amazon Linux 2023 ARM64.

• Caddy HTTPS termination.

• DynamoDB state table for OAuth grants, refresh tokens, MCP sessions, rate-limit buckets, and production metadata cache entries.

• ECR image storage.

• CodeBuild image builds.

• Route53 DNS.

• KMS keys for SecureString values and DynamoDB storage.

• Systems Manager Parameter Store runtime configuration.

• Optional Cognito upstream OIDC provider.

• Runtime service container that reads the promoted image tag from Parameter Store.

Operator-specific values stay outside tracked source. Use environment variables, CI secrets, ignored local shell files, or a secure operator runbook for account IDs, hosted zone IDs, domains, parameter paths, client secrets, and stack names.

Deployment guides:

• Production Deployment

• AWS CDK Deployment

• CDK Operations

• Runtime Parameters

• Source Build

• Identity Provider

• Release Verification

Documentation Map

Development Principles

• Keep runtime code small, named, and domain-owned.

• Keep durable explanations in docs/.

• Keep service tests under test/.

• Keep documentation review manual and reader-focused.

• Keep protocol behavior backed by live service tests.

• Keep commits scoped to one feature, fix, refactor, or documentation slice.