Drive Weftra from Your Assistant

You don't have to use the dashboard or curl to work with Weftra. An AI assistant you already use can draft a spec with you, submit it, answer Weftra's clarifying questions and watch the feature through to a draft pull request. This page has a short quickstart for each one.

You use	Connect through	Time	Needs a public URL?
Claude Code	MCP (local process, or HTTP)	2 min	No
Claude Desktop	MCP (local process)	2 min	No
Claude on the web (claude.ai)	MCP connector + OAuth sign-in	10 min	Yes
ChatGPT — connector	MCP connector + OAuth sign-in	10 min	Yes
ChatGPT — custom GPT action	OpenAPI action (product definition only)	5 min	Yes
Any other MCP client	MCP over HTTP	5 min	Depends where it runs
A terminal or coding agent	The fa CLI	2 min	No

Before you start

You need a running Weftra instance with one enrolled project. The 10-minute quickstart gets you there. Keep two values from it:

• The instance URL. http://127.0.0.1:3100 for a local install.
• The project's API key. The fa_... key returned when you enrolled the project.

Starting from nothing? Give the repository one commit first. A new, empty GitHub repository has no main branch yet, and features currently fail at checkout against it. When you create the repository, tick Add a README (or push any single commit) so main exists, then enroll it. The repository survey has little to read at that point, so you can skip it. With no test_command declared yet the test gate only warns; once the agent has added tests, set test_command on the project and Weftra will refuse to ship without them passing.

Use the project key, never the admin key. Every client on this page acts as that one project and can do only what its key can do. That means submitting and tracking features, co-authoring specs, answering clarifications and proposing product artifacts. No client can approve its own work, change settings, run anything outside the sandbox or see another project. A feature submitted from an assistant goes through the same steps as any other: the project's autonomy mode, the analysis and approval steps, Weftra's own test run, any reviewers you turned on, and a draft PR.

Keep the key out of files you commit and out of command lines. The examples below read it from an environment variable:

export FA_PROJECT_API_KEY=fa_...   # in your shell profile or a secrets manager, not in the repo

What your assistant can do

Every MCP client below gets the same tools:

• Write a spec with you: draft_spec, clarify_spec, refine_spec, estimate_spec
• Submit and track features: submit_feature, get_feature_status, get_feature_progress, list_features, await_feature (waits for the next state that needs action, and reports each phase change while it waits). submit_feature, get_feature_status, await_feature and get_feature_progress all return dashboard_url / logs_url links back to Weftra's dashboard — show them to the person you're working with.
• Answer Weftra's questions: get_clarifications, answer_clarification
• Shape the product: product_list, product_get, product_propose_outcome, product_propose_use_case, product_propose_story, product_review (the Definition-of-Ready check), product_propose_ready (run that same check and, if it passes, mark the artifact ready)
• Check which project it is connected to: list_projects
• Read and change the project's own settings: get_project_config, update_project_config (only the settings this project may change itself; anything else is refused with the reason)
• Open the pull request for a finished feature: create_pr (for a feature that is implemented but has no PR yet)

A good first prompt once connected:

Use Weftra's draft_spec and clarify_spec tools to draft a spec for a GET /healthz endpoint that returns {"status":"ok"}. Relay Weftra's questions to me, show me the estimate, then submit it and wait for it to finish.

Let Weftra write the spec and ask the questions

An assistant tends to do the thinking itself: it writes a complete spec, answers its own open questions, and submits that. Weftra then has nothing left to ask. If you want Weftra to author the spec and question you, two things decide it.

1. What the assistant sends.

The assistant sends	What Weftra does
A short description of the intent	Weftra writes the spec itself, at spec_path (or docs/features/<slug>.md)
A finished spec in spec_content	Weftra commits it byte for byte and never rewrites it

Ask for the first. A prompt like "Submit this to Weftra as a one-paragraph description of the intent. Don't write the spec or answer open questions yourself" keeps the assistant from pre-deciding everything.

2. The project's autonomy mode. Clarifying questions come from Weftra's analysis step, and full_auto skips it. An admin sets the mode on the project:

Mode	Analysis runs?	Who answers Weftra's questions
full_auto	No	Nobody is asked
auto_safe	Yes	You. The feature waits in clarification_needed
full_auto_analyze	Yes	A sandboxed answerer, automatically
po_approval	Yes, after an approver signs off	You

With auto_safe, the loop closes inside the chat: await_feature returns clarification_needed, the assistant calls get_clarifications and shows you the questions, and answer_clarification sends your answers back. The build resumes once every question is answered.

Two optional settings on the project:

• Force clarify (force_clarify, admin-only). Analysis must ask at least one real question on its first pass, even when the request looks clear.
• Require spec approval (require_spec_approval; the project's own key can turn it on). The run pauses after Weftra writes the spec so you can read, edit or reject it before any code is written. Approving needs an admin or an approver who is not the submitter; working alone, set submitter_approver to "record" (see "Running it on your own" in the quickstart).

Want help drafting before anything is submitted? That is what draft_spec, clarify_spec, refine_spec and estimate_spec are for. They run Weftra's Builder, which asks the questions; the assistant relays them. Nothing is created until submit_feature.

Building on work that isn't merged yet. A new feature branches off the project's default branch. To build on an open feature's branch instead, have the assistant pass that branch as base_branch when it submits.

Claude Code

Claude Code starts Weftra's MCP server as a local process. Add a .mcp.json to your project (or run claude mcp add with the same values). ${FA_PROJECT_API_KEY} is read from your environment, so the file is safe to commit:

{
  "mcpServers": {
    "weftra": {
      "command": "npm",
      "args": ["run", "--silent", "mcp-server", "--prefix", "/path/to/weftra"],
      "env": {
        "FA_BASE_URL": "http://127.0.0.1:3100",
        "FA_PROJECT_API_KEY": "${FA_PROJECT_API_KEY}"
      }
    }
  }
}

/path/to/weftra is the Weftra checkout where you ran npm install. Start Claude Code in the project, approve the weftra server when prompted, and run /mcp to check it is connected.

If the operator has turned on the HTTP endpoint (see Any other MCP client), you can connect without a local checkout instead:

{
  "mcpServers": {
    "weftra": {
      "type": "http",
      "url": "https://your-weftra-host/api/mcp",
      "headers": { "Authorization": "Bearer ${FA_PROJECT_API_KEY}" }
    }
  }
}

Claude Desktop

Claude Desktop also starts the server as a local process. Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "weftra": {
      "command": "npm",
      "args": ["run", "--silent", "mcp-server", "--prefix", "/path/to/weftra"],
      "env": {
        "FA_BASE_URL": "http://127.0.0.1:3100",
        "FA_PROJECT_API_KEY": "fa_..."
      }
    }
  }
}

Claude Desktop does not expand environment variables in this file, so the key is written here. The file is on your own machine and never in a repository, but treat it like any other file holding a credential. Restart Claude Desktop; the tools appear under the tools menu in a new chat.

Claude on the web (claude.ai)

claude.ai connects from Anthropic's servers, not your machine. Your Weftra instance therefore needs an HTTPS address reachable from the internet, and you connect by signing in rather than pasting a key.

The operator does this once:

1. Put Weftra behind HTTPS on a public hostname, using a reverse proxy or a tunnel. Weftra listens only on loopback by default; "Put Weftra on the internet with Cloudflare Tunnel and Access" in SETUP.md walks through one way to do it safely. Read it before changing that.

2. Turn on the HTTP endpoint and OAuth sign-in, allow claude.ai's callback address, and restart Weftra:

   FA_MCP_HTTP_ENABLED=true
   FA_MCP_OAUTH_ENABLED=true
   FA_MCP_OAUTH_REDIRECT_ALLOWLIST=https://claude.ai/api/mcp/auth_callback
   APP_BASE_URL=https://your-weftra-host

3. Make sure a named admin account can sign in to the dashboard, with a local account, Google or SSO. Approving a connection issues a project credential, so only an admin can complete it.

Then, in claude.ai:

1. Open the connectors settings and add a custom connector with the URL https://your-weftra-host/api/mcp.
2. Click Connect. A Weftra consent page opens in your browser.
3. Sign in, pick the one project this connector may act for, and check the destination URL on the consent page. It must be claude.ai's callback. The client name shown on the page is whatever the client claims, so it is not proof of who is asking. Click Approve.
4. In a chat, turn on the Weftra connector and try the first prompt above.

The connection lasts as long as its token (one hour by default; the client renews it) and can be revoked at any time. It also stops working if the operator turns OAuth off, removes the admin who approved it, or rotates the project key. See "MCP Client OAuth" in SETUP.md for the token settings and the admin token registry.

ChatGPT — connector

ChatGPT connects as an MCP client in the same way, with the full tool set above. Custom MCP connectors are available on some ChatGPT plans and may need developer mode turned on in ChatGPT's settings.

The operator does this once: the same three steps as for claude.ai, with ChatGPT's callback address on the allowlist. Add both addresses, comma-separated, if you use both assistants:

FA_MCP_OAUTH_REDIRECT_ALLOWLIST=https://claude.ai/api/mcp/auth_callback,https://chatgpt.com/connector_platform_oauth_redirect

Then, in ChatGPT:

1. In ChatGPT's connector settings, create a connector with the MCP server URL https://your-weftra-host/api/mcp and OAuth authentication.
2. Complete the Weftra consent page as above: sign in, pick the project, confirm the destination is chatgpt.com, and click Approve.
3. Turn on the connector in a chat and try the first prompt above.

ChatGPT — custom GPT action

A custom GPT can't use an MCP server, but it can call an OpenAPI action. Weftra publishes a narrower API document for this. It covers the product definition routes only: list, read, draft and version outcomes, roadmap items, use cases, stories and spec links, run the Definition-of-Ready review, and export the bundle. It cannot submit features. Use a connector for that.

1. In the GPT editor, add an action and import the schema from https://your-weftra-host/api/product/openapi.json. The document itself needs no credential.
2. Set authentication to API key → Bearer and paste the project's fa_... key.
3. Optionally add the header X-Weftra-Door: openapi-action to every call. Weftra then records which artifacts this GPT drafted. The header is a label only and grants nothing. (The older X-FA-Door name is still accepted.)

Everything the GPT creates starts as a draft. Marking an artifact ready, retiring it, or building an agent from it stays with an admin or approver. See the Product Definition quickstart for what each artifact holds.

Any other MCP client

Weftra speaks standard MCP over two transports:

• Local process (stdio). Run npm run mcp-server in the Weftra checkout with FA_BASE_URL and FA_PROJECT_API_KEY set in its environment. Use this for any client that starts servers as subprocesses, such as Cursor, VS Code, Zed or Windsurf. The config is the same shape as Claude Code's above.
• Streamable HTTP. POST https://your-weftra-host/api/mcp, off until the operator sets FA_MCP_HTTP_ENABLED=true. Authenticate with Authorization: Bearer fa_..., or with OAuth if the client supports MCP OAuth discovery and its callback address is on the allowlist.

A client running on the same machine as Weftra can use either transport over loopback without a public URL. Only clients that connect from someone else's servers need the HTTPS setup above.

A terminal or coding agent: the fa CLI

For a shell, or a coding agent working in a terminal without MCP, Weftra ships the fa CLI. It calls the same project routes and reads the key from FA_API_KEY or your OS keychain, never from a flag:

export FA_BASE_URL=http://127.0.0.1:3100
export FA_API_KEY="$FA_PROJECT_API_KEY"
npx --prefix /path/to/weftra fa --help

See "Project Sidecar CLI (fa)" in the User Guide for every command.

When something doesn't connect

Symptom	Likely cause
Server exits immediately with a missing-key error	FA_PROJECT_API_KEY is not set in the environment the client started it with
401 on every call	Wrong key, a rotated key, or an admin or user key instead of the project key
404 from /api/mcp	The operator has not set FA_MCP_HTTP_ENABLED=true
503 from /api/mcp	The instance has no ADMIN_API_KEY and is running with open admin; set the key
400 with error -32022 ("unsupported protocol version")	The request declares a version in params._meta that this door does not serve. Send 2026-07-28, or one of the versions listed in error.data.supported
400 with error -32020, "Mcp-Method header does not match the request body"	The Mcp-Method header names a different method from the JSON-RPC body. A proxy or client wrapper has rewritten one of them; make the header match the body
400 with error -32020, "Mcp-Name header does not match the request body"	On a tools/call, the Mcp-Name header is not the tool name in params.name, or it is sent on a method that carries no tool name. Match the header to the body, or drop it
400 with error -32020, "MCP-Protocol-Version header does not match the protocol version in the body"	The request declares 2026-07-28 in params._meta but its MCP-Protocol-Version header is missing or names another version. Send the header with the same value as params._meta
400 with error -32020, "Mcp-Method header is required" or "Mcp-Name header is required for tools/call"	A 2026-07-28 request must carry the mirrored Mcp-Method header, and Mcp-Name on tools/call. Use a client library that sets them
400 with error -32020, "Mcp-Method and Mcp-Name cannot be checked against this body"	The request is a JSON-RPC batch array, which carries Mcp-* headers this door cannot check. Send one JSON-RPC message per POST
Connector says it can't register or redirect	Its callback address isn't on FA_MCP_OAUTH_REDIRECT_ALLOWLIST exactly, or FA_MCP_OAUTH_ENABLED is off
Consent page shows "admin required"	You signed in as an approver; an admin has to approve the connection
Spec-drafting tools refuse with a rate limit	They make model calls on the operator's credential, so they're capped per project per minute; wait and retry

The full tool reference, including the arguments for each tool and how await_feature waits, is in "MCP Server Interface" in the User Guide.