convez.ai
MCP ServerIntegração & APIsAvançado
jmillpps

Encore MCP Base

jmillpps/encore-mcp-base

Backend autenticado TypeScript para GPT Apps, Actions e OAuth

Ver no GitHub
InicialPluginScore · de 0 a 100

Fundação TypeScript pronta para produção que integra aplicativos ChatGPT, GPT Actions, OAuth e OpenID Connect. Fornece um único limite de serviço seguro com suporte a MCP Streamable HTTP, endpoints REST com OpenAPI e provedor OAuth/OIDC privado para autenticação.

Instalação

$npx convez-ai jmillpps/encore-mcp-base

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integração segura de ChatGPT Apps com backend autenticado
  • Implementação de GPT Actions com OpenAPI e OAuth
  • Provedor OIDC privado bridging com identidades externas
  • Deployment em AWS com CDK e gerenciamento de secrets

Veredito

Solução robusta e bem documentada para arquitetos que precisam integrar ChatGPT com autenticação enterprise. Excelente para casos que demandam OAuth, OIDC e operações em AWS, mas requer expertise em TypeScript, protocolos de segurança e infraestrutura cloud.

README

A tradução para o português deste README ainda está na fila.

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.

At A Glance

AreaIncluded behavior
GPT AppsMCP Streamable HTTP at /mcp, legacy HTTP/SSE at /sse and /messages, UI resources, widget assets at /app-ui/*, protocol baseline 2025-11-25.
GPT ActionsREST endpoints, OpenAPI 3.1, public read-only schema at /actions/openapi.json, read-only operation declarations for ChatGPT.
OAuth providerAuthorization code grants, refresh grants, PKCE, client authentication, RS256 access tokens, ID tokens, JWKS, discovery, userinfo.
Upstream identityOIDC authorization bridge through /oauth/callback, upstream userinfo claim validation, generic provider configuration.
SecurityAudience-bound tokens, scope checks, duplicate-header rejection, query bearer rejection, rate limits, diagnostics redaction, hashed stored tokens.
OperationsProduction startup validation, durable JSON state, AWS CDK deployment, Systems Manager Parameter Store, KMS-backed secrets.
MaintainabilitySmall domain modules, shared capability code, protocol adapters, focused tests under test/, docs under docs/.

Standards Baseline

Standard or platformProject useDetail
MCP 2025-11-25GPT Apps transport, tool, and resource protocol.Streamable HTTP at /mcp, legacy HTTP/SSE compatibility, session IDs, protocol negotiation, tool descriptors, resource descriptors, auth challenges.
OpenAI ChatGPT AppsRemote MCP server integration.OAuth account linking, protected resource metadata, Client ID Metadata Document support, read-only tool declarations, UI resource templates, widget CSP metadata, server instructions.
GPT ActionsREST action import and OAuth linking.OpenAPI URL import, OAuth authorization URL, token URL, scopes, bearer-protected operations, read-only action metadata.
OAuth 2.0 and OIDCAccount linking and identity.Authorization code flow, PKCE, refresh tokens, resource indicators, authorization server metadata, protected resource metadata, userinfo, ID tokens, JWKS.
OpenAPI 3.1Actions schema.OAuth2 authorization code flow, JSON response schemas, operation IDs, schema descriptions, and compatibility checks.
AWS CDK and Parameter StoreDeployment path.EC2 runtime, Caddy HTTPS, ECR, CodeBuild, Route53, Systems Manager parameters, SecureString secrets, KMS.

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["OAuth 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 OAuth store for client grants, tokens, and signing keys.

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

RequirementUse
Node.js and npmInstall packages, run TypeScript checks, run Node test suites, and run local tools.
Encore CLIRun the TypeScript service locally and deploy through Encore-supported service wiring.
Public HTTPS originConnect ChatGPT Apps, import GPT Actions, complete OAuth account linking, and publish discovery metadata.
Upstream OIDC providerSupply the signed-in user identity through authorization, token, and userinfo endpoints.
AWS CLI and CDK toolsUse the included AWS deployment path, Parameter Store seeding, stack operations, and release checks.

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 durable store at var/oauth-store.json. Automated tests start a local upstream OIDC provider for real authorization-code flows.

Local Defaults

AreaLocal value
Service originhttp://localhost:4000
OAuth callbackhttp://localhost:4000/oauth/callback
Default scopesopenid profile email
Development clientslocal-test, gpt-actions, gpt-apps-mcp
Durable storevar/oauth-store.json
Actions schema exportvar/actions.openapi.json

ChatGPT Setup Values

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

ChatGPT fieldValue
GPT Apps MCP server URLhttps://service.example.com/mcp
GPT Actions schema import URLhttps://service.example.com/actions/openapi.json
OAuth authorization URLhttps://service.example.com/oauth/authorize
OAuth token URLhttps://service.example.com/oauth/token
OAuth scopesopenid profile email
Privacy policy URLhttps://service.example.com/privacy

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

ToolRequired scopesPurpose
health.checknoneReturn service reachability and version metadata.
health.status_cardnoneRender service health as an inline ChatGPT UI card.
identity.profileopenid profile emailReturn the signed-in OIDC profile.
identity.profile_cardopenid profile emailRender the signed-in OIDC profile as an inline ChatGPT UI card.
auth.sessionopenidReturn token subject, client ID, audience, and granted scopes.

MCP UI Resources

Resource URIRequired scopesPurpose
ui://widget/health-status-card-v1.htmlnoneHTML component template for service health.
ui://widget/profile-summary-card-v1.htmlopenid profile emailHTML component template for the signed-in OIDC profile.

Widget Framework Assets

AssetPurpose
/app-ui/mcp-widget-bridge-v1.jsShared bridge for initial tool output and later tool-result messages.
/app-ui/tool-result-card-base-v1.cssShared responsive card layout for declarative tool-result widgets.

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

Actions Endpoints

EndpointRequired scopesPurpose
GET /healthnoneReturn service reachability.
GET /privacynoneReturn the public privacy policy text.
GET /actions/openapi.jsonnoneReturn the ChatGPT Actions OpenAPI document.
GET /actions/profileopenid profile emailReturn the authenticated OIDC profile.
GET /actions/sessionopenidReturn token session metadata.

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

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.
  • OAuth state, refresh tokens, rate-limit buckets, and MCP sessions use a durable JSON store.
  • Sensitive tokens and session IDs 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

AreaRequired evidence
Public URLsPUBLIC_ISSUER_URL, MCP_RESOURCE_URL, and ACTIONS_AUDIENCE use public HTTPS values.
OAuth clientsProduction client records contain exact redirect URIs, allowed scopes, allowed resources, auth method, PKCE policy, and secret hashes where required.
Upstream identityThe upstream OIDC provider accepts /oauth/callback and returns sub, email, and email_verified through userinfo.
SecretsRaw client secrets, upstream IdP secret, and signing key material are loaded from secure runtime configuration.
StorageOAUTH_STORE_PATH points to durable storage owned by the service user.
OriginsALLOWED_ORIGINS contains explicit browser origins used by ChatGPT and local development.
OpenAPI/actions/openapi.json returns OpenAPI 3.1 with OAuth URLs on the deployed origin.
VerificationTargeted tests pass for the changed surface and npm run check passes before release.

Project Layout

PathPurpose
auth/OAuth provider, upstream OIDC bridge, client registry, token issuance, storage, rate limits, discovery.
mcp/MCP transports, JSON-RPC protocol, sessions, tool registry, UI resource registry, widget framework, validation, auth challenges.
actions/GPT Actions endpoints, bearer validation, privacy endpoint, OpenAPI document.
shared/Configuration, HTTP helpers, JSON helpers, diagnostics, crypto, service metadata.
ci/cdk/AWS CDK stack, deployment commands, runtime parameter seeding, image build helpers.
tools/Local operator tools and static repository checks.
test/Service behavior tests, protocol tests, security tests, CDK tests, support harnesses.
docs/API references, architecture, deployment, development, maintenance, and user guides.

The development rule is simple: put shared behavior in one focused module, then expose it through MCP and Actions 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.
  • ECR image storage.
  • CodeBuild image builds.
  • Route53 DNS.
  • KMS key for SecureString values.
  • Systems Manager Parameter Store runtime configuration.
  • Optional Cognito upstream OIDC provider.
  • Runtime service container with durable OAuth state.

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:

Documentation Map

NeedStart here
Run locallyLocal Development
Connect GPT AppsGPT Apps Setup
Add ChatGPT UI resources and widgetsMCP Apps UI Resources
Import GPT ActionsGPT Actions Setup
Understand architectureArchitecture Overview
Review APIsAPI Documentation
Check external specsExternal References
Add a capabilityAdding Capabilities
Test changesTesting
Operate storageStorage Maintenance
Rotate keysSigning Key Rotation

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.
Ver o original no GitHub

Bom para

Relacionados