forta-mcp

MCP server for the Forta OAuth2 identity provider. Gives Claude Code direct access to users, platforms, roles, grants, and token introspection.

appleby.cloud platform · MCP server · auth.appleby.cloud

Overview

Forta is the identity provider for the whole appleby.cloud ecosystem, so almost every auth bug starts here. This server turns "why is this user getting a 403 from Keyring" into one forta_list_grants call instead of a manual database dig.

Quick Start

npx forta-mcp --setup

Prompts for your Forta API URL and token, writes the config to ~/.mcp.json. Restart Claude Code afterwards.

Manual Setup

{
  "mcpServers": {
    "forta": {
      "command": "npx",
      "args": ["-y", "forta-mcp"],
      "env": {
        "FORTA_API_URL": "https://auth.appleby.cloud",
        "FORTA_API_TOKEN": "frt_..."
      }
    }
  }
}

Generate a token from the Forta dashboard under Settings > API Tokens, or:

curl -X POST https://auth.appleby.cloud/admin/api-tokens \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"claude-code","expires_in":"365d"}'

Tokens are frt_-prefixed, owned by the creating user, and require that user to be a Forta super-admin for the /admin tools. The plaintext is returned once and stored only as a SHA-256 hash.

Secret values are masked

Every response is passed through a masking step before it reaches the model. Anything that looks like a credential keeps its first two characters and loses the rest to a fixed-width tail — supersecret becomes su**********.

That is enough to tell two credentials apart, or to confirm a rotation actually changed something, and not enough to use. The tail is a fixed width so the mask does not reveal the real length.

This matters most on the tools that mint a credential and return it exactly once — forta_create_platform and forta_rotate_platform_credentials (a client_secret) and forta_create_api_token (a plaintext frt_ token). Read the real value from the Forta dashboard instead. Introspection metadata (active, sub, exp, token_type) is left readable.

Set FORTA_ALLOW_SECRET_VALUES=1 to turn masking off if you genuinely need a working value.

Tools

Health & identity

| Tool | Description | |------|-------------| | forta_health | API health and database connectivity | | forta_get_self | Which user this token authenticates as |

Users

| Tool | Description | |------|-------------| | forta_list_users | List users with status and super-admin flag | | forta_get_user | Single user with metadata and linked identities | | forta_update_user | Update name, email, status, super-admin, password | | forta_delete_user | Soft-delete a user ⚠️ |

Platforms

| Tool | Description | |------|-------------| | forta_list_platforms | All registered OAuth platforms | | forta_get_platform | Full platform config | | forta_create_platform | Register a platform (returns client_secret once) | | forta_update_platform | Update platform config | | forta_delete_platform | Delete a platform ⚠️ | | forta_rotate_platform_credentials | Rotate client_secret ⚠️ |

Roles

| Tool | Description | |------|-------------| | forta_list_roles | Roles on a platform, with permissions | | forta_get_role | Single role | | forta_create_role | Create a role | | forta_update_role | Update name or permission set | | forta_delete_role | Delete a role ⚠️ |

Grants

| Tool | Description | |------|-------------| | forta_list_grants | Who can access what, with which role — start here for 403s | | forta_create_grant | Grant a user access to a platform | | forta_revoke_grant | Revoke a grant ⚠️ | | forta_check_grant | Check a grant by client_id, exactly as a service sees it |

Tokens

| Tool | Description | |------|-------------| | forta_introspect_token | RFC 7662 introspection — is this token expired, or bound elsewhere? | | forta_list_api_tokens | Active API tokens with expiry and last use | | forta_create_api_token | Mint a token (plaintext returned once) | | forta_revoke_api_token | Revoke a token ⚠️ |

⚠️ = destructive. Tool descriptions state the blast radius; rotate_platform_credentials in particular takes the platform down until its deployed config is updated.

Contributing & further reading

• forta-api — the API this wraps
• go-forta — Go SDK; v1.3.0+ accepts these tokens
• keyring-mcp — uses the same frt_ token