Profiles support multiple named service account tokens tracked in profile.json.sa_tokens. This enables distinct client_id and scope sets, for example CI automation versus read-only dashboards while sharing a single signing keypair.

Command reference

Use the following commands to manage service account tokens:
Command Purpose
sa-token <profile_name> Creates or replaces a named token entry.
sa-tokens <profile_name> Lists all tokens including names, client IDs, scopes, and primary marker. Add --json for machine output.
remint-all <profile_name> Rotates the key pair and remint every token.

Flags for the sa-token command

The following table lists the most commonly used flags, along with their purpose and detailed usage notes. For the full list of flags, run this help command:
./mcpgen sa-token -h
Flag Purpose Notes
--name NAME Unique logical token name The default string is reserved for primary generated at profile creation.
--scopes scope1 scope2 ... Space-separated scopes Replaces existing scopes for that token
--client-id ID Custom client identifier Defaults to derived profile-based ID if omitted
--days N Validity period in days Default is 365
--issuer ISS Override issuer Defaults to profile issuer if set
--primary Mark token as primary Only one primary allowed; updates client header

List tokens

The following example command lists all tokens:
./mcpgen sa-tokens myprof
The command produces the following output:
NAME       CLIENT_ID      SCOPES                 PRIMARY  EXPIRES
default    svc-myprof     schema.read tags.read  yes      2026-10-11
ci-bot     ci-bot         orders.read            no       2025-11-10
The following example outputs the JSON representation of the sa_tokens array from the profile. The jq filter then extracts the first token object.
./mcpgen sa-tokens myprof --json | jq '.sa_tokens[0]'
Here is an example of the sa_tokens section inside the profile.json file:

{
  "sa_tokens": [
    {
      "name": "default",
      "filename": "sa/token.jwt",
      "client_id": "svc-myprof",
      "issuer": "oemcp-local",
      "scopes": ["schema.read", "tags.read"],
      "days": 365,
      "primary": true
    },
    {
      "name": "ci-bot",
      "filename": "sa/ci-bot.jwt",
      "client_id": "ci-bot",
      "issuer": "oemcp-local",
      "scopes": ["orders.read"],
      "days": 30,
      "primary      "primary": false
    }
  ]

Primary token semantics

Only the primary token is embedded into client/mcp.json as the service account header. The --sa-token <name> flag lets you override the default primary token and select any named token configured in profile.json.sa_tokens. This behavior supports least privilege access and role-based workflows.

The following examples show how to override the default token and specify a named token:
  • This example runs the MCP client for the profile named myprof and uses the service account token named ci-bot for authentication. This approach is useful when you want to switch from the default token to a token with different scopes or permissions.
    ./mcpgen client myprof --sa-token ci-bot
  • This example runs the MCP client for the profile named myprof, uses the service account token named ci-bot for authentication, and also invokes a specific tool called getOrders with empty arguments ({}). This approach allows you to run a targeted API operation under the authorization of the ci-bot token, ensuring the correct access level for that tool.
    ./mcpgen client myprof --sa-token ci-bot --tool getOrders --args '{}'
Note: To mark a different token as primary, re-issue it with --primary. The previous primary flag is cleared automatically.

Example procedure to rotate service account tokens

Follow these steps to perform token rotation:
  1. To add a new limited-scope token, run the following command to create a token named dashboard with the products.read scope, a custom client ID, and a validity of 90 days:
    ./mcpgen sa-token myprof --name dashboard 
--scopes products.read --client-id dashboard --days 90
  2. To promote the new token to primary, make the dashboard token the primary token for the profile:
    ./mcpgen sa-token myprof --name dashboard --primary
  3. To rotate all keys and tokens after quarterly review, use the remint-all command to generate a new key pair and re-mint all tokens:
    ./mcpgen remint-all myprof
  4. To verify the updated tokens, list all tokens in JSON format to confirm the changes:
    ./mcpgen sa-tokens myprof --json

Revoke or delete a token

Currently, there is no direct command for token removal. To remove a token:
  1. Delete its JWT file.
  2. From the generated/<profile_name>/profile.json file, remove the sa_tokens object.
  3. Optionally, run remint-all if you also want a key rotation.

Security considerations

Ensure these recommendations to maintain token integrity and prevent compromise:
  • All tokens share the same signing key. A compromise of the private key invalidates security for every token. Use remint-all promptly.
  • Distinct scopes per token support least privilege and simplified audit trails in external systems.