Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superradcompany/tool-cli/llms.txt

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

HTTP MCP servers that connect to SaaS APIs often require users to authenticate before the tool can make requests on their behalf. tool-cli handles the entire OAuth flow — browser redirect, token exchange, refresh, and secure local storage — so neither you nor your users have to manage it manually.
API keys and tokens never leave your machine. All credentials are encrypted at rest in your local tool store.

​
When to use OAuth

Use oauth_config when your HTTP MCP server:
  • Connects to a third-party SaaS API (GitHub, Google, Notion, Slack, etc.)
  • Requires a browser-based authorization flow
  • Issues short-lived access tokens that need automatic refresh
For static API keys or bearer tokens, use user_config with sensitive: true instead.

​
Declaring OAuth in your manifest

Add oauth_config inside mcp_config in your manifest.json:
manifest.json
{
  "manifest_version": "0.3",
  "name": "my-saas-tool",
  "version": "0.1.0",
  "server": {
    "transport": "http",
    "mcp_config": {
      "url": "https://api.example.com/mcp/",
      "oauth_config": {
        "clientId": "your-client-id",
        "authorizationUrl": "https://example.com/oauth/authorize",
        "tokenUrl": "https://example.com/oauth/token",
        "scopes": ["read", "write"]
      }
    }
  }
}

​
oauth_config fields

FieldTypeDescription
clientIdstringPre-registered OAuth client ID for your application
authorizationUrlstringAuthorization endpoint where users grant access
tokenUrlstringToken endpoint for exchanging the auth code for access tokens
scopesstring[]OAuth scopes to request (e.g., ["read", "write"])
All fields are optional — omit any that the server discovers dynamically via OAuth metadata endpoints.

​
How the flow works

1

Trigger authentication

Run tool config set for the tool. tool-cli detects the oauth_config and opens the authorization URL in your browser.
tool config set my-saas-tool
2

User grants access

The browser loads the provider’s consent screen. The user logs in and approves the requested scopes.
3

Token exchange

tool-cli receives the authorization code via a local redirect, exchanges it for access and refresh tokens at tokenUrl, and stores them encrypted on disk.
4

Automatic token use

tool run and tool call pick up the stored tokens automatically. Requests to the HTTP server include the access token. tool-cli refreshes the token transparently when it expires.

​
Scaffolding an OAuth tool

Use tool init with the --url and --oauth-client-id flags to generate a manifest pre-configured for OAuth: 
tool init . --url https://api.example.com/mcp/ --oauth-client-id abc123
Add authorization and token URLs if they differ from the OAuth metadata discovery endpoint: 
tool init . \
  --url https://api.example.com/mcp/ \
  --oauth-client-id abc123 \
  --oauth-authorization-url https://example.com/oauth/authorize \
  --oauth-token-url https://example.com/oauth/token \
  --oauth-scopes "read,write"

​
Managing OAuth credentials

# Trigger or re-run the OAuth flow
tool config set my-saas-tool

# Check stored config (tokens are shown redacted)
tool config get my-saas-tool

# Remove stored credentials
tool config unset my-saas-tool

Build docs developers (and LLMs) love

Get started for freeTalk to us