JWT-authenticated MCP servers with login flows

JWT vs OAuth — what's different here?

Cast's Bearer Token mode is for static tokens stored once. For APIs that issue short-lived JWTs after a username/password login, you combine Bearer auth with Custom Params: Cast uses the credentials to call your login endpoint, obtains a JWT, and injects it as Authorization: Bearer <token> on every tool call — refreshing transparently before expiry.

1. Start the test server in jwt mode

cd cast-mcp/test-server
npx ts-node src/index.ts --mode jwt --port 3456

  🔐 JWT login endpoint: POST http://localhost:3456/auth/login
     Sample credentials:
       username: admin  password: password
       username: alice  password: alice123
  🔄 Refresh endpoint: POST http://localhost:3456/auth/refresh

Tokens are short-lived (15 min). The refresh token lasts 7 days. Cast handles both.

2. Create a workspace and upload the spec

New workspace → Upload → http://localhost:3456/openapi.json.

3. Configure auth — Bearer Token

Switch to Configure. Select Bearer Token. Leave the token value empty — we acquire the token dynamically via the login endpoint configured in the next step.

4. Add custom injection params

Next to the Save button is a sliders icon — click it to open Custom Params. These are workspace-level key/value pairs Cast stores encrypted and makes available at request time. Add the three params below.

How Cast acquires and caches the token

{
  "username": "admin",
  "password": "password"
}

// Response
{
  "accessToken": "eyJ...",
  "refreshToken": "...",
  "expiresIn": 900
}

Cast caches the access token in Redis for expiresIn − 30 seconds, then re-authenticates automatically. If the server issues a refresh token, Cast uses it to extend the session without a full re-login.

5. Enable tools

6. Connect and test

{
  "mcpServers": {
    "test-jwt": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.getcast.io/test-jwt-cmpquev5h000a"
      ]
    }
  }
}

On the first tool call, Cast logs in, gets a token, and immediately calls the tool — all in one round trip from the client's perspective. Open the Logs tab to see both the login request and the tool call in sequence.