Skip to main content

Documentation Index

Fetch the complete documentation index at: https://terminal49-docs-search-v2-endpoint.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
OAuth E2E Smoke Test

Use this runbook to validate the hosted MCP OAuth 2.1 integration.

​
Prerequisites

  1. curl and jq installed.
  2. Reachable API and MCP endpoints.
  3. A redirect URI for client registration (for example http://localhost:5050/callback).
  4. Optional: a valid OAuth access token to run authenticated MCP calls.

​
Environment variables

export API_BASE_URL="https://api.terminal49.com"
export MCP_BASE_URL="https://mcp.terminal49.com/mcp"
export MCP_REDIRECT_URI="http://localhost:5050/callback"
export MCP_CLIENT_NAME="Terminal49 MCP Smoke Client"

# Optional for authenticated phase
export MCP_ACCESS_TOKEN="<oauth_access_token>"

​
Run

From the API repo root: 
bash scripts/mcp-oauth-e2e-smoke.sh

​
What this validates

  1. Discovery endpoint returns required metadata:
  • issuer
  • authorization_endpoint
  • token_endpoint
  • revocation_endpoint
  • code_challenge_methods_supported
  1. Dynamic registration succeeds:
  • POST /oauth/register returns client_id
  • no client_secret is returned
  1. Unauthenticated MCP request is standards-compliant:
  • POST /mcp returns 401
  • WWW-Authenticate includes: Bearer resource_metadata="https://api.terminal49.com/.well-known/oauth-authorization-server"
  1. Authenticated MCP calls (if MCP_ACCESS_TOKEN provided):
  • initialize returns success
  • tools/list returns a non-empty tools list

​
Troubleshooting

  1. 401 with missing resource_metadata:
  • Verify T49_MCP_RESOURCE_METADATA_URL in the MCP deployment.
  1. Registration fails with invalid_client_metadata:
  • Validate redirect_uris format.
  • Use https:// callbacks or localhost http callbacks.
  1. OAuth bearer token rejected:
  • Confirm token contains mcp scope.
  • Confirm issuer/audience/JWKS env vars: WORKOS_MCP_ISSUER, WORKOS_MCP_AUDIENCE, WORKOS_MCP_JWKS_URL.
  1. Internal fallback verification fails:
  • Confirm T49_MCP_TOKEN_VERIFY_URL and T49_MCP_INTERNAL_AUTH_TOKEN match Rails internal endpoint config.