Documentation

Connect an agent

Helen’s Foundry exposes your whole workspace over the Model Context Protocol (MCP), so an agent can read the strategy behind a ticket before it writes a line of code. Point any MCP client at your workspace URL and authenticate.

Your workspace endpoint

Use the workspace-scoped MCP URL — it pins every call to this workspace. The exact URL for the active workspace is on Settings → MCP Clients.

https://next.hf.dev/api/mcp/w/<workspace-id>
Open MCP Clients →

Authentication

API key

Best for CI, scripts, and server-to-server agents.

Create a key under Settings → API keys and send it as a bearer token. Keys are scoped to one workspace.

Clerk OAuth

Best for interactive clients such as Claude Code, VS Code, and Codex.

Add the workspace URL without an Authorization header. Most clients open the browser consent flow when they connect; Codex requires one `codex mcp login helens-foundry` command first. The client then stores the resulting token.

Configure your client

Copy the workspace-specific configuration from Settings → MCP Clients. The examples below use <workspace-id> only to show the configuration shape; use the ready-made snippet instead of replacing it manually. These examples use OAuth, so do not add an Authorization header.

Claude Code

  1. 1. Create or update .mcp.json (project root).
  2. 2. Paste this workspace-scoped configuration: 
    {
  "mcpServers": {
    "<workspace-name> (<workspace-id>)": {
      "type": "http",
      "url": "https://next.hf.dev/api/mcp/w/<workspace-id>"
    }
  }
}
  3. 3. Start the client, complete the browser sign-in, and verify the connection: Run `claude` in the project, find the "<workspace-name> (<workspace-id>)" server after OAuth completes, and call workspace_summary to verify its workspace name and ID.

VSCode / Copilot

  1. 1. Create or update .vscode/mcp.json.
  2. 2. Paste this workspace-scoped configuration: 
    {
  "servers": {
    "<workspace-name> (<workspace-id>)": {
      "type": "http",
      "url": "https://next.hf.dev/api/mcp/w/<workspace-id>"
    }
  }
}
  3. 3. Start the client, complete the browser sign-in, and verify the connection: Open the Copilot Chat panel and confirm "<workspace-name> (<workspace-id>)" appears in the MCP server list.

Codex

  1. 1. Create or update .codex/config.toml.
  2. 2. Paste this workspace-scoped configuration: 
    [mcp_servers."<workspace-name> (<workspace-id>)"]
url = "https://next.hf.dev/api/mcp/w/<workspace-id>"
  3. 3. Start the client, complete the browser sign-in, and verify the connection: Run `codex mcp login` with the connection name shown above to complete OAuth. Then start a Codex session and call workspace_summary to verify the workspace name and ID.

Tool reference

Browse the MCP tool reference to inspect every registered tool, its purpose, and its parameters. It is generated from the same tool registry clients receive, so the docs and deployed surface stay in lockstep.

Access and permissions

The workspace in your MCP URL is the access boundary. After OAuth or API-key authentication, the client can read that workspace and call the write tools exposed by the MCP server, including tools that create, update, link, or reconcile artifacts. Only connect clients you trust with that access.

The GitHub App is separate from MCP. It requests read access to repository contents and metadata, plus write access to checks, issues, and pull requests. Helen uses those permissions to inspect PR diffs and context, post check runs and review feedback, and manage its PR labels. The app does not have permission to push commits or change repository contents.

What your agent can do

Once connected, an agent can search and read artifacts, walk a context chain, see what’s ready to work on, and propose changes back into the graph — all scoped to the workspace you pinned. Start it with a workspace summary, then have it pull the chain for whatever it’s about to touch.