MCP Server

CodeFloe hosts a Model Context Protocol (MCP) server at https://mcp.codefloe.com/mcp. AI assistants that speak MCP can use it to read and work with your repositories, issues, pull requests, releases and CI quota, without you installing anything locally.

It runs forgejo-mcp with additional tools for CodeFloe features such as Pages and CI quota. The source of the CodeFloe build is codefloe/forgejo-mcp-codefloe.

How it works

The server has no account and no credentials of its own. Every request from your assistant carries your own CodeFloe access token, and the server forwards each call to the CodeFloe API with that token. The assistant can therefore do exactly what the token allows, and nothing more.

The server does not store or log tokens. Requests without a token are refused with 401.

MCP or a CLI?

An assistant can also work with CodeFloe through git and a command-line client such as forgejo-cli (fj), if it can run shell commands. Both use the same API and the same token scopes, so pick by what the assistant can do and what the task needs.

Use the MCP server when:

• the assistant has no shell, such as a chat app or an IDE chat panel;
• you do not want to install and log in to a CLI on every machine;
• you need the CodeFloe-specific Pages and CI quota tools, which no CLI offers.

Use git and a CLI when:

• the assistant works in a local checkout, such as Claude Code or Codex in a terminal: cloning, committing and pushing are git operations the MCP server does not do;
• the work is mostly scripted or chained, where piping one command into the next beats one tool call per step;
• the context window is tight: the definitions of the server’s 175 tools take up a noticeable part of it in clients that load all tools up front.

The two combine well: a coding agent can use git and fj for the repository and the MCP server for the rest.

Create an access token

1. Open Settings > Applications.
2. Under Generate new token, give the token a name such as mcp.
3. Select the scopes the assistant needs, then select Generate token.
4. Copy the token; CodeFloe shows it only once.

Grant only what the assistant needs:

Use	Scopes
Browse code, issues and pull requests	read:repository, read:issue, read:user
Also open issues, comment and create pull requests	write:repository, write:issue, read:user
Organization CI quota and organization repos	add read:organization

Do not grant admin scopes to a token you hand to an assistant. Use a separate token per assistant or machine, so you can revoke one without affecting the others.

Connect your assistant

Store the token in an environment variable, here CODEFLOE_TOKEN, rather than pasting it into a config file. The server accepts both Authorization: Bearer <token> and Authorization: token <token>.

Claude Code

claude mcp add --transport http codefloe https://mcp.codefloe.com/mcp --header "Authorization: Bearer $CODEFLOE_TOKEN"

Add --scope user to make the server available in all your projects.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.codefloe]
url = "https://mcp.codefloe.com/mcp"
bearer_token_env_var = "CODEFLOE_TOKEN"

VS Code

Add to .vscode/mcp.json; VS Code asks for the token on first use and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "codefloe-token",
      "description": "CodeFloe access token",
      "password": true
    }
  ],
  "servers": {
    "codefloe": {
      "type": "http",
      "url": "https://mcp.codefloe.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:codefloe-token}"
      }
    }
  }
}

Any other client that supports the streamable HTTP transport works the same way: point it at https://mcp.codefloe.com/mcp and send the Authorization header with every request.

Available tools

The server offers around 175 tools. Most come from forgejo-mcp and cover repositories, files, branches, commits, issues, pull requests and reviews, labels, milestones, releases, wikis, organizations, notifications and packages. See the forgejo-mcp tool list for the full set.

The CodeFloe-specific tools all start with codefloe_:

Tool	Does
codefloe_get_my_ci_quota	Your CI minutes usage and limits for the current month
codefloe_list_my_ci_quota_records	The CI runs counted towards your quota, most expensive first
codefloe_get_org_ci_quota	An organization’s CI minutes usage and limits
codefloe_list_org_ci_quota_records	The CI runs counted towards an organization’s quota
codefloe_get_repo_pages	A repository’s Pages configuration
codefloe_update_repo_pages	Enable Pages or change the source branch
codefloe_disable_repo_pages	Disable Pages for a repository
codefloe_get_repo_pages_status	The state of the latest Pages deployment
codefloe_get_repo_pages_log	The end of the latest Pages build log
codefloe_replace_repo_pages_domains	Set the custom domains of a Pages site
codefloe_add_repo_pages_branch	Publish an additional branch as its own site
codefloe_remove_repo_pages_branch	Stop publishing an additional branch

The organization quota tools require organization owner rights, and all Pages tools require repository administrator rights, as the matching settings pages do.

Limits

Each token can make 300 requests per minute. Above that, the server answers 429 with a Retry-After header, and other tokens are not affected. The per-IP limits described in Defense & Protection apply as well.

---

If you run into a problem or miss a tool, please open an issue in the CodeFloe forum.