Skip to main content

Connect @simplr-ai/mcp with browser OAuth

@simplr-ai/mcp exposes API endpoints registered in Simplr's AI Gateway to Codex and other MCP clients. Version 2.1 adds browser-based OAuth, OS-keychain storage, and automatic refresh-token rotation. With this flow, you do not need to paste an API key or portal token into a terminal command, configuration file, prompt, or chat.

Sign in once​

npx -y @simplr-ai/mcp@2.1.0 login

The command starts a temporary callback on 127.0.0.1, opens https://simplr-ai.com, and uses OAuth Authorization Code with S256 PKCE. In the browser:

  1. Sign in to Simplr.
  2. Choose an organization.
  3. Choose an active secret API key. Simplr binds the OAuth grant to the key's database record; it does not retrieve or display the original key value.
  4. Choose a DEV, UAT, or PROD environment whose test/live mode matches the selected key.
  5. Approve the requested MCP tool and redacted network-log scopes.

The CLI stores the short-lived access token and rotating refresh token in macOS Keychain, Windows Credential Manager, or the platform secret service. It does not print the access or refresh token. The authorization code is single-use and expires after five minutes; access tokens expire after 15 minutes and refresh automatically.

Tool execution is proxied by Simplr. For each outbound call, Simplr creates a delegation credential that lasts no more than 20 seconds, sends it only to the registered endpoint in its configured authentication header, and revokes it when execution finishes. This credential is not returned to the local MCP process in the OAuth or tool response.

Add it to Codex​

codex mcp add simplr \
  --env SIMPLR_API_URL=https://api.simplr-ai.com \
  -- npx -y @simplr-ai/mcp@2.1.0

Or add the equivalent project configuration:

[mcp_servers.simplr]
command = "npx"
args = ["-y", "@simplr-ai/mcp@2.1.0"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.simplr.env]
SIMPLR_API_URL = "https://api.simplr-ai.com"

Restart Codex after adding the server, then open /mcp to confirm that Simplr is connected. This is an STDIO MCP server, so authentication is handled by simplr-mcp login; codex mcp login is reserved for OAuth-capable remote HTTP MCP servers.

Manage the local session​

npx -y @simplr-ai/mcp@2.1.0 status
npx -y @simplr-ai/mcp@2.1.0 logout

status reports only whether a stored session exists and whether refresh is needed. logout asks the API to revoke the OAuth token family, then deletes the local keychain entry even if that request cannot reach the API. After successful server revocation, the API immediately rejects subsequent use of every access and refresh token in the family. The revocation endpoint accepts either token type and invalidates the whole family.

If the revocation request fails because the API is unreachable, deleting the local keychain entry prevents this CLI from refreshing. An existing access JWT can remain valid for up to 15 minutes, while a copied or stolen refresh token can remain usable until the token family expires, for up to 30 days, unless the selected key, organization, membership, or environment is revoked first.

The API checks the selected key, organization, membership, and environment on each MCP request. Revoking the selected API key, removing the user from the organization, or suspending the organization therefore blocks those requests independently of refresh-token revocation.

Other environments​

Production is the default. To connect to another trusted Simplr deployment, set both URLs for login and for the MCP server:

SIMPLR_API_URL=https://api.example.internal \
SIMPLR_APP_URL=https://app.example.internal \
npx -y @simplr-ai/mcp@2.1.0 login

Credentials are stored in a separate keychain entry for each API URL. Only loopback callback URLs are accepted.

Troubleshooting​

  • Not signed in: run login again. Do not set SIMPLR_USER_TOKEN for a new installation.
  • No key appears: create an active secret key in Dashboard → API Keys. Public browser keys are intentionally excluded.
  • No environment appears: the environment mode must match the selected key (test for DEV/UAT, live for PROD).
  • Access stopped after working: check that the key, organization, membership, and environment remain active, then sign in again.
  • Browser did not open: copy the manual authorization URL printed by the CLI into a trusted browser, and leave the terminal running while the local callback waits for sign-in to finish.