Fudge agent setup

@withfudge/design configures supported agent clients to use Fudge's hosted MCP server and installs the small agent-guidance pack. It does not run a local MCP server or carry a local copy of the corpus.

Hosted access

The MCP endpoint is:

https://api.withfudge.com/mcp

The hosted MCP uses standard OAuth and requires an active Standard, Pro, or Studio subscription. Your MCP client opens the authorization page on design.withfudge.com, where an existing Fudge browser session is reused. There is no CLI login step and the installer does not store a token.

Install

npx -y @withfudge/design@latest install --client codex

Install for detected supported clients:

npx -y @withfudge/design@latest install --all

Use --local to write the selected client's project configuration instead of its global configuration. This changes configuration scope only; it still points to the hosted endpoint.

Some clients do not support remote MCP servers through their configuration file. For those clients the installer reports the client's native connector setup path instead of installing a local proxy.

The equivalent generic MCP configuration is:

{
  "fudge": {
    "type": "http",
    "url": "https://api.withfudge.com/mcp"
  }
}

Do not add an authorization header, cookie, local command, or environment secret to this configuration. The MCP client discovers OAuth from the hosted endpoint and manages its own tokens.

MCP contract

The hosted server exposes one corpus data tool:

• query_fudge using contract mnestic-query-v1.

It also exposes the live resource fudge://agent/guide.md. Agents read that resource, introspect the current Mnestic schema with CozoDB's ::relations and ::columns queries, and then compose bounded CozoScript themselves. The server does not offer named lookup, inspection, taxonomy, similarity, export, or presentation convenience tools.

query_fudge accepts:

{
  "contract_version": "mnestic-query-v1",
  "script": "::relations",
  "parameters": {},
  "expected_generation": 11,
  "max_rows": 500,
  "max_bytes": 524288
}

Only contract_version and script are required. CozoScript is passed through as opaque text. The hosted boundary adds typed parameters, result bounds, a timeout, and generation fencing; it does not parse or rewrite queries.

Mnestic's service token remains server-side. OAuth credentials terminate at the Fudge Worker and are never forwarded to Mnestic.

Skills

The default skill pack contains:

• fudge-search
• fudge-export
• fudge-design-md

Install only the skills with:

npx -y @withfudge/design@latest install --skill-only

The skills provide task guidance; they do not implement a second data-access path. The live MCP guide and current Mnestic introspection remain authoritative.

Doctor

npx -y @withfudge/design@latest doctor --client codex

Doctor validates the hosted OAuth challenge and discovery chain plus the installed skill pack and client configuration. Tool and guide access are verified by the MCP client after browser authorization; fudge login is not part of that flow.

Development

Run the Worker and Mnestic locally, then point an MCP client directly at:

http://127.0.0.1:8789/mcp

This is still Streamable HTTP. There is no supported fudge mcp stdio command and no local CLI query relay.