AI Service Integration Starter

A reusable Next.js starter for exposing product capabilities to ChatGPT, Claude, and other MCP clients. It includes a stateless Streamable HTTP MCP endpoint, OAuth discovery, strict resource/audience binding, optional social sign-in, and defensive structured-output helpers.

The repository intentionally contains no product data model, company domain, credentials, or deployment configuration. It is a safe starting point, not a ready-to-publish OAuth provider.

What is included

OAuth authorization-server metadata and issuance routes deliberately return 501 until the application supplies a durable implementation. This prevents a demo-only in-memory flow from being advertised as a deployable security boundary.

Related MCP server: GPT MCP Service

Quick start

corepack enable
pnpm install
cp .env.example .env.local
pnpm dev

Useful endpoints:

• GET /health

• POST /mcp

• GET /.well-known/oauth-protected-resource

• GET /.well-known/oauth-authorization-server

• GET|POST /api/auth/* when at least one social provider is configured

Run the local checks:

pnpm typecheck
pnpm lint
pnpm test --run
pnpm build

Apply this starter with an agent

Give the agent the repository plus the product specification, then require it to work through these gates in order. Do not ask it to copy another product's OAuth tables or tools verbatim.

1. Define the boundary. Name the product capability, users, MCP tools, read/write effects, data policy, public origins, and deployment target.

2. Replace placeholders. Update APP_NAME, PUBLIC_APP_ORIGIN, OAUTH_ISSUER, MCP_RESOURCE, PROTECTED_RESOURCE_METADATA_URL, allowed browser origins, scopes, tool names, schemas, and copy. Origins must come from configuration, never an incoming Host header.

3. Implement identity and consent. Decide how a signed-in user approves an MCP client. Keep social sign-in separate from OAuth delegation and never merge accounts using email or display name alone.

4. Implement durable OAuth state. Add DCR, one-time authorization codes, refresh-token families, hashing, rotation, reuse detection, and migrations in a store that survives restarts. Only short-lived authorization codes may be process-local, and production should normally persist those too.

5. Preserve resource binding. Carry the exact canonical resource through authorize, code, token, refresh, JWT aud, and MCP verification. Reject missing or mismatched values at every boundary.

6. Add product tools. Replace example_lookup; annotate every tool accurately (readOnlyHint, destructiveHint, openWorldHint) and validate both input and output at runtime.

7. Add the model adapter only if needed. Use a structured-output API supported by the chosen model, then validate the parsed value against the product schema. Retry only transient failures and do not log API keys or credential-bearing URLs.

8. Prove the whole flow. Test discovery → DCR → PKCE S256 → consent → code exchange → MCP call → refresh rotation, then restart the service and repeat with the existing client and refresh token. Add negative tests for wrong and missing resources, redirect URI mismatch, code replay, and refresh reuse.

Suggested task prompt:

Adapt this starter for <product>. Read README.md and AGENTS.md first.
Keep all public origins explicit in environment variables. Implement the OAuth
store with migrations and restart-safe tests. Preserve resource binding from the
authorize request through the access-token aud claim and MCP verification.
Replace the example MCP tool with <tools>, including accurate annotations and
runtime input/output validation. Do not copy product-specific names, data, URLs,
or credentials from another repository. Run typecheck, lint, unit tests, build,
and the documented end-to-end OAuth flow before reporting completion.

An agent is not finished when the code compiles. It is finished when the real client flow and restart behavior pass against the intended deployment topology.

Architecture

MCP client
  -> POST /mcp
  <- 401 + WWW-Authenticate(resource_metadata=...)
  -> protected-resource metadata
  -> authorization-server metadata
  -> authorization code + PKCE S256 + user consent
  -> access token whose aud equals MCP_RESOURCE
  -> POST /mcp with Bearer token

See docs/architecture.md for invariants and docs/oauth-store.sql for a portable persistence model.

Environment

Copy .env.example to .env.local. Public origins and the MCP resource are separate settings even when they currently share a host. Do not infer any of them from request headers.

OAUTH_SIGNING_SECRET is a development convenience for HS256 verification. Use asymmetric keys, rotation, and a published JWKS in a real multi-service system.

Public-release checklist

Keep the GitHub repository private until all items are complete:

• Confirm the MIT license and SPACEWALK copyright are still intended.

• Search the full tracked tree and Git history for organization names, private hosts, credentials, customer data, internal package registries, and proprietary copied code.

• Replace placeholder privacy, terms, support, icon, and documentation URLs.

• Enable secret scanning and push protection.

• Review dependency licenses and run a vulnerability scan.

• Verify the repository from a clean clone with no untracked local files.

• Treat making the repository public as a separate human-approved action.

License

MIT © 2026 SPACEWALK. See LICENSE.