Remote MCP server

fremforge runs a Model Context Protocol server at:

https://frem.sh/_app/mcp

It gives an AI assistant read access to your organisation’s fremforge data: security findings, the component inventory, deployments, package access, policies, runner usage and CI logs. There is nothing to install. The server is remote and speaks the Streamable HTTP transport.

What the tools are

Every tool is one operation of the fremforge REST API, and a tool call is that REST call made with your token. The tool can do exactly what your token can do through https://frem.sh/_app/api/v1, with the same scopes, rate limits and audit trail. A 403 from the REST API comes back as a tool error with the same explanation.

• Read-only. All tools are GET operations and are marked readOnlyHint for your client. No tool changes anything.
• 41 tools, for example whoami, list_sast_findings, list_dependency_findings, list_secret_findings, search_components, list_vulnerable_components, get_dependency_paths, list_repo_deployments, get_actions_run_logs, get_org_policy and get_package_access. Your client lists them all, with descriptions, when it connects.
• Not included: Git repositories, issues, pull requests and workflow run lists. Those are served by the Forgejo API at https://frem.sh/api/v1, not by the fremforge API.
• Large results are cut at 100,000 characters, with a note saying so. Use the tool’s limit, cursor or filter arguments to narrow them.

Token

The server accepts a fremforge API token (ffp_…) as a bearer token. Create one at https://frem.sh/<org>/_admin/api-tokens, and give it the read scopes for the tools you want to use. Each tool’s description names the scope it needs, for example findings:read, components:read, policy:read or runners:read.

Other credentials are refused, including Forgejo personal access tokens and Forgejo OAuth tokens. With an API token, the Forgejo tools (repositories, pull requests, issues) are not available: those need the sign-in connector.

Start with the whoami tool. It shows which tenant and scopes the token carries.

Claude Code

claude mcp add --transport http fremforge https://frem.sh/_app/mcp \
  --header "Authorization: Bearer ffp_xxxxxxxxxxxxxxxxxxxxxx"

Or in .mcp.json:

{
  "mcpServers": {
    "fremforge": {
      "type": "http",
      "url": "https://frem.sh/_app/mcp",
      "headers": { "Authorization": "Bearer ${FREMFORGE_TOKEN}" }
    }
  }
}

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "fremforge": {
      "url": "https://frem.sh/_app/mcp",
      "headers": { "Authorization": "Bearer ffp_xxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Sign in instead of a token. Leave out headers, and Cursor signs you in with OAuth. Its MCP documentation says Cursor supports OAuth for servers that require it:

{
  "mcpServers": {
    "fremforge": { "url": "https://frem.sh/_app/mcp" }
  }
}

Cursor registers itself with frem.sh, so you need no client ID. It then opens frem.sh in your browser, and you sign in and allow access as described in Sign-in and consent. Signed in, Cursor also gets the read-only Forgejo tools. The desktop app receives the sign-in on your own machine; Cursor on the web and Cursor Agents receive it at cursor.com. To stop, remove the server or switch it off under Customize, and also withdraw it on frem.sh.

Mistral

Le Chat. An administrator adds a custom MCP connector:

1. Server URL: https://frem.sh/_app/mcp
2. Authentication: HTTP Bearer Token, with your ffp_… token.

Le Chat sorts tools into read and write functions. All fremforge tools are read-only.

Agents API and SDK. Pass the token as a header. In the Python SDK, give MCPClientStreamableHTTP a StreamableHTTPServerParams(url="https://frem.sh/_app/mcp", headers={"Authorization": "Bearer ffp_…"}). When you register a Studio connector (POST /v1/connectors), put the same header in headers.

Le Chat can also sign you in with OAuth instead of a token: see Le Chat.

Connectors with sign-in: claude.ai, ChatGPT, Le Chat

Chat apps that add an MCP server as a connector sign you in with OAuth instead of a token. fremforge is the authorization server for https://frem.sh/_app/mcp. It supports Client ID Metadata Documents, so a connector that identifies itself with a published document needs no registration. It also supports dynamic client registration for connectors that register themselves. You never enter a client ID or secret.

Sign-in and consent

The connector opens frem.sh in your browser. What follows is the same for every connector:

1. Sign in to frem.sh as usual, with your organisation’s single sign-on and second factor where they apply. If you are already signed in, this step is skipped.
2. fremforge’s consent page shows the connector’s name, the address it will send you back to and what it can do: read, as you, the fremforge data and repositories you can read. If the connector identified itself with a metadata document, the page shows that document’s full address. fremforge has not verified the name, so allow it only if you are adding the connector yourself.
3. Choose Allow. You return to the chat app, and the connector shows as connected.

A connected assistant can use the tools above, plus read-only Forgejo tools: list_repos, get_repo, get_repo_tree, get_file_contents, list_branches, list_commits, get_commit, get_commit_diff, list_pull_requests, get_pull_request, get_pull_request_diff, list_pull_request_files, list_pull_request_reviews, list_issues, get_issue, list_issue_comments, list_workflow_runs, get_workflow_run and list_workflow_jobs. It cannot change anything.

It has exactly the access you have through the API. The organisation tools answer for the organisations you own, and read-only where you are an auditor. The Forgejo tools answer for the repositories Forgejo lets you read. Your organisation’s IP allowlist applies to the connector as it applies to you.

The connector never receives your frem.sh password or your tokens. Its own access lasts an hour at a time and is renewed in the background.

claude.ai

Custom connectors work in Claude on the web, in Claude Desktop and in Cowork. Free plans allow one custom connector. Claude’s custom connector guide has the current steps:

1. Pro and Max: go to Customize → Connectors, choose + Add, then Add custom connector. Team and Enterprise: an owner goes to Organization settings → Connectors, chooses Add, then Custom → Web. Members then find the connector under Customize → Connectors and choose Connect.
2. Name it, for example fremforge, and enter the server URL https://frem.sh/_app/mcp.
3. For the OAuth client, keep Use Claude’s published identity. Register automatically works too. Leave request headers empty.
4. Choose Add, then sign in and allow access as described in Sign-in and consent.

To use it, choose + in a chat, then Connectors, and switch fremforge on for that conversation. To remove it, use Remove or the menu next to the connector on the same page, then also withdraw it on frem.sh.

ChatGPT

ChatGPT calls custom MCP servers plugins or apps. Adding one needs developer mode, and on Business, Enterprise and Edu plans a workspace admin may have to allow it. OpenAI’s guide to connecting an MCP server to ChatGPT has the current steps:

1. Open ChatGPT Plugins, choose +, then Add custom MCP server.
2. Enter a name and description. Under Connection, choose Public endpoint and enter https://frem.sh/_app/mcp.
3. For authentication, choose OAuth. ChatGPT finds frem.sh’s sign-in from the server, so no client ID is needed. Confirm the risk warning and choose Create as a plugin.
4. Sign in and allow access as described in Sign-in and consent.

ChatGPT shows the tools it found. To use them, type @ in a new conversation and choose the plugin. To remove it, disconnect or delete it in ChatGPT’s app settings, then also withdraw it on frem.sh.

Le Chat

In Le Chat, an administrator adds custom connectors. On Free, Pro and Student plans the account owner is the administrator. Mistral’s MCP connector documentation has the current steps:

1. Open Connectors, choose + Add Connector and switch to the Custom MCP Connector tab.
2. Enter a connector name without spaces, for example fremforge, and the server URL https://frem.sh/_app/mcp.
3. Choose Connect. Le Chat detects OAuth 2.1 and registers itself.
4. Sign in and allow access as described in Sign-in and consent.

Each user can pre-approve functions under Connectors → My Connectors, on the connector’s Functions tab. Otherwise Le Chat asks before each call. All fremforge functions are read-only. To stop using it, remove it on the Connectors page and also withdraw it on frem.sh. Le Chat also accepts an ffp_ token as an HTTP bearer token instead of sign-in, as in Mistral above.

Desktop apps and redirects

A desktop or command-line client that signs in through the browser needs the code back on the same device. fremforge accepts two kinds of redirect for this:

• Loopback: http://127.0.0.1/…, http://[::1]/… or http://localhost/…. The port is ignored when matching, so a client can listen on any free port (RFC 8252 section 7.3). Claude Code and the Cursor desktop app work this way.
• App schemes, such as cursor://…, vscode://… or com.example.app:/callback, for clients without a client secret. They match exactly, port included. The consent page names the scheme and warns that any installed app can claim one, so allow it only for an app you are connecting yourself.

Some schemes are never accepted as redirects, whatever their case:

• schemes a browser or the operating system treats as content or navigation: javascript, data, file, blob, ftp, about, ws, wss, vbscript, view-source, chrome, chrome-extension, moz-extension and intent;
• fremforge’s own names: fremforge, frem and sh.frem;
• http on anything but a loopback address.

PKCE is required in every case.

Block connectors for an organisation

Connectors are allowed by default. An owner can block them under Org admin → Security → AI connectors, or with PUT /orgs/{org}/policy and {"ai_connectors": {"access": "blocked"}}. While they are blocked, every connector call for that organisation’s data, including its repositories, is refused with 403. API tokens are not affected. Each change is recorded in the audit log as tenant.ai_connectors.blocked or tenant.ai_connectors.allowed.

Withdraw a connector

Withdrawing a connector ends all its sessions at once. List your connectors, then delete the one to withdraw, with a credential that carries your identity, such as the one fremforge auth login stores:

curl -sS https://frem.sh/_app/api/v1/users/me/connector-grants -H "Authorization: Bearer $TOKEN"
curl -sS -X DELETE https://frem.sh/_app/api/v1/users/me/connector-grants/<id> -H "Authorization: Bearer $TOKEN"

To connect it again, add it again; it asks for your consent again. Revoking the fremforge connector application under your Forgejo Settings → Applications, or a disabled account, also ends every connector of yours the next time one is used.

Check the connection

curl -sS https://frem.sh/_app/mcp \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

Errors

Sovereignty

Your assistant’s vendor receives what the tools return, in the same way it receives the files you open. fremforge does not send your data to any AI vendor. The MCP server is part of the fremforge API and runs in the same EU platform.