Skip to main content

Coding-agent prompt

The fastest way to wire AuthSec into an existing MCP server is to let a coding agent do it. The Protect step in the AuthSec dashboard emits a prompt with every value already filled in for your resource server; this page documents the underlying template so you know what the agent is being asked to do and so the prompt has a permanent URL you can reference in a runbook or PR description.

Where to get the live prompt​

  1. Open your application's Protect tab in the AuthSec dashboard.
  2. In Step 2 — Wire the AuthSec SDK, pick your language (Go, Python, or TypeScript) and click Copy coding-agent prompt.
  3. Paste it into Claude Code or Cursor with your MCP server repo open. The agent will install the SDK, add the wrapper, and wire the env vars listed in Step 3.

The dashboard prompt embeds your actual resource-server ID, issuer, introspection URL, JWKS URL, supported scopes, and registration modes — nothing in the template below; the template uses placeholders so it is safe to share in docs.

What the agent does​

The prompt instructs the agent to:

  1. Install the AuthSec SDK for the chosen language (go get … / pip install authsec-sdk / npm install @authsec/sdk).
  2. Wrap the existing MCP HTTP handler with MountMCP / mount_mcp / mountMCP. No hand-rolled protected-resource metadata, no manual challenge logic.
  3. Pull the issuer, JWKS URL, introspection URL, resource server ID, resource URI, and introspection secret from environment variables (the AUTHSEC_* names listed under Environment setup).
  4. Keep upstream service credentials (GitHub PAT, etc.) server-side and distinct from the AuthSec user token.
  5. Verify that unauthenticated requests get a Bearer challenge pointing at AuthSec metadata, that tools/list hides unauthorized tools, and that tools/call returns insufficient_scope for blocked tools.

Prompt template​

Note: The dashboard substitutes every {{placeholder}} below with the real value for your resource server. Don't paste this version directly into an agent — copy from the dashboard, or fill the placeholders in by hand.

You are integrating AuthSec into an MCP server in {{LANGUAGE}}.

Use these exact AuthSec and resource server values:
- Resource server name: {{NAME}}
- Public base URL: {{PUBLIC_BASE_URL}}
- Protected base path: {{PROTECTED_BASE_PATH}}
- Resource URI: {{RESOURCE_URI}}
- MCP endpoint URL: {{MCP_ENDPOINT_URL}}
- Metadata path: {{METADATA_PATH}}
- Metadata URL: {{METADATA_URL}}
- Supported scopes: {{SUPPORTED_SCOPES}}
- Registration modes: {{REGISTRATION_MODES}}
- OAuth issuer: {{ISSUER}}
- AuthSec API / SDK policy server: {{API_ORIGIN}}
- Authorization endpoint: {{AUTHORIZE_URL}}
- Token endpoint: {{TOKEN_URL}}
- JWKS endpoint: {{JWKS_URL}}
- Introspection endpoint: {{INTROSPECTION_URL}}
- Resource server registry endpoint: {{REGISTRY_URL}}

AuthSec responsibilities:
- Serve the authorization server for MCP OAuth and PAR-backed login flows
- Issue and validate user tokens
- Enforce RBAC and granted scopes
- Provide protected-resource metadata and bearer challenges through the SDK
- Maintain consent, auditability, and resource server registration

MCP server responsibilities:
- Keep upstream service credentials server-side only
- Execute the actual tools
- Map tools to scopes/policy rules
- Never forward AuthSec user tokens to upstream systems

{{INSTALL_LINE}}

Use this import baseline:
{{IMPORT_GUIDANCE}}

Implement the integration in this order:
1. Use the SDK's MountMCP/mount_mcp/mountMCP path as the canonical
   integration path. Do not hand-wire protected-resource metadata when the
   SDK can mount it.
2. Configure issuer, authorization server, JWKS URL, introspection URL,
   resource server ID, resource URI, resource name, and the one-time
   introspection secret from AuthSec.
3. Preserve existing non-AuthSec server behavior unless AuthSec mode is
   explicitly enabled.
4. Keep the upstream service credential separate from AuthSec tokens.
5. Expose the protected MCP path at {{PROTECTED_BASE_PATH}} and let the SDK
   derive metadata from {{RESOURCE_URI}}.
6. Treat {{METADATA_URL}} as the discovery URL. For path-based resources,
   the bare /.well-known/oauth-protected-resource path is not the canonical
   metadata route.
7. Verify unauthenticated requests receive a Bearer challenge pointing
   clients to AuthSec metadata.
8. Verify authenticated requests can only see tools permitted by granted
   scopes.

Validation checklist:
- tools/list hides unauthorized tools
- tools/call returns insufficient_scope for blocked tools
- the server emits protected-resource metadata at {{METADATA_URL}}
- the server uses MountMCP / mount_mcp / mountMCP as the default setup
  path; manual mux wiring is for advanced cases only
- tokens are validated against AuthSec
- upstream provider calls still use server-side credentials only
- the configured resource URI remains {{RESOURCE_URI}}

If the resource server is a GitHub MCP server, keep the GitHub PAT or
installation token server-side. The AuthSec principal should only decide
whether the tool is allowed; it should not replace the upstream GitHub
credential.

Generate production-grade integration code, not pseudocode.

Versioning​

This page tracks the dashboard prompt template. When the SDK's canonical entry points change (a new wrapper helper, a new required config field) the prompt is updated in Authsec-ui/src/features/resource-servers/resource-server-utils.ts (buildIntegrationPrompt) and mirrored here.

See also​