ForgeLore
Agent tooling

ForgeLore MCP server

Connect Codex, Claude Code, Cursor, and other MCP clients to ForgeLore with predictable tools, structured outputs, safety metadata, pagination, and recovery guidance.

Required token

Use a ForgeLore AI Access token. Store it in `FORGELORE_AGENT_TOKEN`; do not paste token values into chat, commits, logs, or docs.

Before you begin

Create a ForgeLore AI Access token with the minimum required repositories and scopes. Confirm that your MCP client supports remote servers and environment-variable header values.

Configure an MCP client

Use the CLI to generate configuration or paste this into a project-local MCP file supported by your client.

$forgelore mcp config
{ "mcpServers": { "forgelore": { "url": "https://forgelore-mcp-production.up.railway.app/mcp", "headers": { "authorization": "Bearer ${FORGELORE_AGENT_TOKEN}" } } } }

Discover first

MCP validates token status before `tools/list`; then call `get_capability_manifest` or read `forgelore://agent/manifest` before choosing tools.

Use structured output

Every tool returns JSON `structuredContent` so agents can validate results instead of scraping text.

Respect safety metadata

Tools advertise read-only, destructive, dry-run, idempotency, confirmation, scope, and retry behavior.

Recover predictably

Use `recover_failed_operation` after validation, scope, lock, readiness, or rate-limit failures.

Recommended tool order

  1. Call `get_capability_manifest`.
  2. Call `discover_environment`.
  3. Call `list_repositories`, then `inspect_repository_state` for the selected repository.
  4. Call `list_locks` before any asset edit.
  5. Run dry-run write operations when supported.
  6. Use idempotency keys for retries on writes.

Authentication boundaries

Anonymous, invalid, expired, and revoked MCP requests are rejected before `tools/list`. Scoped tokens can only access repositories and actions granted by their ForgeLore role and token scopes.

Never expose: bearer tokens, connect tokens, private keys, provider secrets, payment details, or sensitive checkout URLs.

Useful commands

$forgelore agent manifest
$forgelore agent session
$forgelore repo inspect <repoId>
$forgelore lock create <repoId> Content/Map.umap --dry-run
$forgelore agent recover FORBIDDEN

Verify the connection

Confirm the client can list tools, call `get_capability_manifest`, and list only the repositories granted to the token. If tool discovery fails, validate the session with the CLI before changing client configuration.