example-org MCP Server

Install and register the example-org MCP server with the MCP-enabled agent/tooling you use.

1) Install

Option A: install from npm (recommended for agent machines)

pnpm add -g @foundation0/api

Option B: run from npm without installing

pnpm dlx @foundation0/api f0-mcp --help

The runnable entrypoint is f0-mcp (available from bin when installed globally).

2) Environment

The server supports:

• GITEA_HOST (recommended, required by git-backed tools)
• FALLBACK_GITEA_HOST (fallback host variable)
• GITEA_TOKEN (for authenticated actions)
• MCP_TOOLS_PREFIX (or --tools-prefix) to namespace tools in clients
• MCP_ALLOWED_ROOT_ENDPOINTS (or --allowed-root-endpoints) to whitelist API root endpoints
• MCP_DISABLE_WRITE (or --disable-write) to expose read-only tools only
• MCP_ENABLE_ISSUES (or --enable-issues) to allow issue endpoints when write mode is disabled
• MCP_ADMIN (or --admin) to expose admin-only destructive endpoints

Useful defaults:

• default server name: f0-mcp
• default server version: 1.0.0

3) Registering with different MCP agents

A) .codex/config.toml

[mcp_servers.example]
command = "bun"
  args = ["x", "@foundation0/api", "f0-mcp"]
enabled = true
startup_timeout_ms = 20_000
env = {
  GITEA_HOST = "https://gitea.example.com",
  GITEA_TOKEN = "your-token",
  MCP_TOOLS_PREFIX = "example"
}

If you installed globally with pnpm add -g, swap command to:

command = "f0-mcp"
args = []

B) Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "example": {
      "command": "bun",
      "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
      "env": {
        "GITEA_HOST": "https://gitea.example.com",
        "GITEA_TOKEN": "your-token"
      }
    }
  }
}

Use command: "f0-mcp" instead of bun run ... if you prefer the global install.

C) Cursor

Use the same command/args/env block in your MCP server configuration area:

{
  "command": "bun",
  "args": ["x", "@foundation0/api", "f0-mcp", "--tools-prefix", "example"],
  "env": {
    "GITEA_HOST": "https://gitea.example.com",
    "GITEA_TOKEN": "your-token"
  }
}

D) Any MCP-capable client

For any MCP client, register a command-based server with:

• command: "bun" and args: ["x", "@foundation0/api", "f0-mcp", ...flags], or
• command: "f0-mcp" if installed globally.

Add environment variables for host/token and optional MCP_TOOLS_PREFIX.

4) Optional server flags

f0-mcp --help

# examples
f0-mcp --tools-prefix=example --server-name=my-example
f0-mcp --tools-prefix api --server-version 1.2.3
f0-mcp --allowed-root-endpoints projects
f0-mcp --allowed-root-endpoints agents,projects
f0-mcp --disable-write
f0-mcp --allowed-root-endpoints projects --disable-write
f0-mcp --disable-write --enable-issues
f0-mcp --admin
f0-mcp --admin --disable-write --enable-issues

• --tools-prefix is useful when running multiple MCP servers side-by-side.
• --server-name and --server-version are mostly metadata but can help identify logs and client tool sets.
• --allowed-root-endpoints restricts exposed tools to selected root namespaces (agents, projects).
• --disable-write removes write-capable tools (for example create/update/delete/sync/set/main/run operations).
• --enable-issues is a special-case override for --disable-write: issue endpoints remain enabled (fetchGitTasks, readGitTask, writeGitTask).
• projects.syncTasks and projects.clearIssues are admin-only and hidden by default; they are exposed only with --admin (or MCP_ADMIN=true).