Configuring OAuth for pre-registered apps

Stainless can generate an MCP server that handles the full OAuth 2.0 authorization code flow, so you don’t need separate tooling to manage access tokens. This is designed for APIs like Google that require a pre-registered OAuth app and don’t support dynamic client registration.

If your API already supports OAuth natively, see OAuth resource metadata instead.

Prerequisites

• A Stainless project with a TypeScript SDK and MCP server configured
• A registered OAuth application with your API provider (you need the client ID and client secret)

Configure the authorization flow

Add the oauth_authorization_flow block to your Stainless config:

targets:
  typescript:
    options:
      mcp_server:
        oauth_authorization_flow:
          token_url: https://oauth2.googleapis.com/token
          authorization_url: https://accounts.google.com/o/oauth2/v2/auth
          scopes:
            - https://www.googleapis.com/auth/calendar.readonly

To match your API provider, replace the URLs and scopes with values from its OAuth documentation.

Generate and build the SDK

Generate a new version of your TypeScript SDK from the Stainless dashboard or CLI. Then, from your SDK repository root, build the SDK:

./scripts/bootstrap && ./scripts/build

Run the MCP server

To start the MCP server in HTTP mode with your OAuth credentials, run:

npx -y my-org-mcp \
  --transport=http \
  --port=3000 \
  --oauth-client-id=YOUR_CLIENT_ID \
  --oauth-client-secret=YOUR_CLIENT_SECRET

The server handles the authorization code flow automatically. When an MCP client connects, the server redirects you to the authorization URL, exchanges the authorization code for an access token, and uses that token for subsequent API requests.

Connect your MCP client

Point your MCP client to the running server. For clients that use mcpServers.json:

{
  "mcpServers": {
    "my-org-mcp": {
      "url": "http://localhost:3000/"
    }
  }
}

When you first connect, your MCP client redirects you to the OAuth provider’s consent screen. After you authorize, the server stores the access token and handles refresh automatically.

Test the server

To verify the server is working, connect with the MCP Inspector:

npx -y @modelcontextprotocol/inspector@latest

Select Streamable HTTP as the transport type and enter http://localhost:3000 as the URL.

Use the --debug flag when starting the server for verbose logging. Run npx -y my-org-mcp --help for a full list of available options.