Authentication

Public tools and endpoints need no credentials. Account tools on the MCP server use OAuth sign-in or a CarScout API key.

The REST API and the public MCP tools need no credentials. The MCP account tools need a paid CarScout plan and one of these credentials:

  • OAuth sign-in: your client asks you to sign in to CarScout and allow access. Use this in clients that support remote MCP servers with OAuth, such as Claude and Claude Code.
  • API key: a key you create in CarScout and add to your client's configuration. Use this in clients without OAuth support.

OAuth scopes

Scope Tools
carscout:read list_scouts, get_scout, check_limits, get_alerts
carscout:write create_scout, update_scout, delete_scout, dismiss_alert, submit_feedback

To build your own OAuth client, follow these steps:

  1. Send a request for an account tool to https://mcp.usecarscout.com/mcp without a token. The 401 Unauthorized response has a WWW-Authenticate header that points to the protected resource metadata.
  2. Read the metadata at https://mcp.usecarscout.com/.well-known/oauth-protected-resource/mcp. It names the authorization server, https://clerk.usecarscout.com, and the scopes.
  3. Run the OAuth authorization code flow with PKCE against that server.
  4. Send the access token in the Authorization: Bearer header.

A token without the scope a tool needs gets 403 Forbidden with error="insufficient_scope" in the WWW-Authenticate header.

API keys

To create an API key, follow these steps:

  1. Sign in to CarScout.
  2. Go to Settings > Account.
  3. Click Generate API Key, and copy the key. CarScout shows it only once.

Send the key in the Authorization header:

Authorization: Bearer CARSCOUT_API_KEY

Replace CARSCOUT_API_KEY with your API key.

You can also pass the key as a key query parameter in the server URL. Prefer the header, because URLs can end up in logs.

An account can have up to 5 API keys. An API key has full access to the account tools, whatever the OAuth scopes. To replace a key, revoke it in Settings > Account and generate a new one. CarScout stores only a SHA-256 hash of each key.