# Installing the Weft MCP server (instructions for AI agents)

One board for you and your AI: hand tasks to ChatGPT, Claude, Cursor or Codex and get a report back.

Weft is a **hosted, remote** MCP server. There is nothing to clone, build or
run locally: no npm install, no Docker, no environment variables. Setting it
up means adding one URL to the host's MCP configuration.

| | |
|---|---|
| Endpoint | `https://letsweft.com/api/mcp` |
| Transport | Streamable HTTP (MCP 2026-07-28; 2025-11-25 and earlier revisions for older clients) |
| Auth | OAuth 2.1 (Authorization Code + PKCE, dynamic client registration) **or** a Weft access token sent as `Authorization: Bearer wft_…` |
| Manifest | https://letsweft.com/.well-known/mcp.json (per-client config snippets) |

A free Weft account is required: https://letsweft.com/sign-up (no card).

## Choose the auth path

1. **OAuth (preferred).** If the host can add a remote MCP server by URL and
   open a browser, add `https://letsweft.com/api/mcp` with no headers. The
   host registers itself dynamically; there is no client ID or secret to
   paste. The user signs in to Weft and approves access once.
2. **Access token.** If the host has no OAuth support (scripts, CI, some
   CLIs), ask the user to create a token at
   https://letsweft.com/account (guide:
   https://letsweft.com/docs/access-tokens) and send it as the header
   `Authorization: Bearer <token>`. The token is shown once and can be
   revoked from the same page. Never write it into a file that is committed.
3. **stdio-only host.** Bridge it: `npx -y mcp-remote https://letsweft.com/api/mcp`.

A generic JSON entry, for hosts that read an `mcpServers` map:

```json
{ "mcpServers": { "weft": { "url": "https://letsweft.com/api/mcp" } } }
```

## Per-client setup

- [Claude Code](https://letsweft.com/claude-code): `claude mcp add --transport http weft …` — one shell command.
- [Claude Desktop](https://letsweft.com/claude-desktop): add a custom connector in Settings → Connectors (Pro/Max/Team/Enterprise).
- [Cursor](https://letsweft.com/cursor): "Add to Cursor" one-click install button on the page, or a JSON entry in `~/.cursor/mcp.json`. Listed at https://cursor.directory/plugins/weft.
- [VS Code](https://letsweft.com/vscode): the `letsweft.weft` extension (VS Code Marketplace or Open VSX) registers the server for you — agent mode on any Copilot plan, free tier included. Without it: `.vscode/mcp.json`, or "MCP: Open User Configuration" for every workspace. OAuth in the browser.
- [Google Antigravity](https://letsweft.com/antigravity): JSON entry with `serverUrl` in `~/.gemini/config/mcp_config.json`, then Authenticate in Agent Settings → Customizations (OAuth). IDE and CLI share the config.
- [ChatGPT](https://letsweft.com/chatgpt): published plugin in the ChatGPT Plugin Directory — Plugins (sidebar or Settings) → search "Weft" → Connect. All plans, including Free.
- [Codex CLI](https://letsweft.com/codex): TOML entry in `~/.codex/config.toml`.
- [GitHub Copilot CLI](https://letsweft.com/copilot-cli): `/mcp add` inside a session, or `~/.copilot/mcp-config.json`. Leave the headers empty — Copilot registers itself over OAuth and keeps the token.
- [Gemini CLI](https://letsweft.com/gemini-cli): official extension — `gemini extensions install https://github.com/AndreiFinogeev/weft-gemini-extension` (a manual `~/.gemini/settings.json` entry also works).
- [Gemini](https://letsweft.com/gemini): gemini.google.com → Settings → Connected Apps → Custom apps → paste the URL; OAuth with dynamic registration, no credentials. Personal Google Accounts in the US (18+, Keep Activity on, English) only; once added it also works in the mobile app.
- [JetBrains IDEs](https://letsweft.com/jetbrains): IntelliJ, PyCharm, WebStorm, GoLand, Rider — through Junie (`~/.junie/mcp/mcp.json`). AI Assistant takes the same URL but does not run the OAuth handshake, so Weft belongs in Junie.
- [Kiro](https://letsweft.com/kiro): `~/.kiro/settings/mcp.json` — Streamable HTTP with dynamic client registration, no headers and no API key. Amazon Q Developer CLI takes the same endpoint.
- [Warp](https://letsweft.com/warp): Settings → Agents → MCP servers → add by URL; OAuth in the browser, token kept on the device. Cloud agents cannot open a browser — add a managed MCP installation instead.
- [Goose](https://letsweft.com/goose): `goose configure` → "Remote Extension (Streamable HTTP)". No client ID: goose registers itself during the OAuth handshake.
- [Muse Code](https://letsweft.com/muse-code): an `mcp_servers` entry with `transport: "streamable_http"` in `~/.config/muse/settings.json` (keep `schema_version: 1`), then `muse mcp login weft` to sign in through the browser.
- [Kimi Code CLI](https://letsweft.com/kimi-cli): `kimi mcp add --transport http --auth oauth weft …` — one shell command, then `kimi mcp auth weft` to sign in. No client ID: Kimi registers itself over OAuth. The entry lands in `~/.kimi/mcp.json`.
- [iFlow CLI](https://letsweft.com/iflow-cli): `iflow mcp add --scope user --transport http weft … -H "Authorization: Bearer <token>"` — a token from Settings → Access tokens, since iFlow has no OAuth (https://letsweft.com/docs/access-tokens). Lands in `~/.iflow/settings.json`.
- [CodeBuddy](https://letsweft.com/codebuddy): `codebuddy mcp add --scope user --transport http weft … -H "Authorization: Bearer <token>"` — access token, not OAuth. `codebuddy mcp list` health-checks it.
- [DeepSeek Harness](https://letsweft.com/deepseek): one `@deepseek-ai/dsh-mcp-client` instance per server in the profile patch (`- insert:` at the top level), transport `streamable-http`, access token in the Authorization header. dsh needs DEEPSEEK_API_KEY to boot at all.
- [Trae](https://letsweft.com/trae): Settings → MCP → Add manually — Streamable HTTP with an `Authorization: Bearer <token>` header. The marketplace lists local servers only.
- [Qoder](https://letsweft.com/qoder): MCP → Add → Manual, `type: "http"` with an `Authorization: Bearer <token>` header. Same entry in the IDE and the Qoder CLI.
- [opencode](https://letsweft.com/opencode): `opencode mcp add weft --url …` — one command, then `opencode mcp auth weft`. Discovers, registers itself and runs PKCE; no client ID, no token.
- [Amp](https://letsweft.com/amp): `amp mcp add weft --header "Authorization=Bearer <token>" …` for local settings (access token), or `amp mcp remote add weft <url> --auth oauth --personal` for a server stored on your Amp account.
- [Amazon Q Developer CLI](https://letsweft.com/amazon-q): `~/.aws/amazonq/mcp.json` with `type: "http"`, then `/mcp` inside `q chat` to authorise. Same endpoint and same OAuth as Kiro.
- [Cherry Studio](https://letsweft.com/cherry-studio): Settings → MCP Servers → Add → Quick Create, type Streamable HTTP; OAuth opens in the browser on save. An access token in an Authorization header is the fallback where that build's OAuth is broken.
- [Raycast](https://letsweft.com/raycast): "Install MCP Server" with OAuth Type: Dynamic, then Sign In in the browser. Needs Raycast Pro.
- [Perplexity](https://letsweft.com/perplexity): Settings → Connectors → Custom → Remote MCP; leave the OAuth client ID blank. Pro, Max or Enterprise only, and the Comet browser still takes catalog connectors only.
- [Grok](https://letsweft.com/grok): grok.com/connectors → New → Custom — xAI calls it "Bring Your Own MCP". OAuth 2.1 + PKCE.
- [Le Chat](https://letsweft.com/le-chat): Connectors → + Add → Custom MCP Connector; Le Chat detects the OAuth on its own. Adding one is an administrator action (on Free, Pro and Student the account owner is the administrator).
- [Lovable](https://letsweft.com/lovable): add a chat connector — Settings → Connectors → Personal connectors → Custom → New MCP server (OAuth). Works on all plans; connectors do not consume build credits.
- [Replit](https://letsweft.com/replit): one-click "Add to Replit" install link on the page, or replit.com/integrations → "MCP Servers for Replit Agent" → "Add MCP server" (OAuth auto-detected). Account-level — works across all Replit Apps.
- [Windsurf](https://letsweft.com/windsurf): add a remote MCP server in Cascade settings.
- [Cline](https://letsweft.com/cline): add a remote MCP server in the VS Code Cline panel.
- [Zed](https://letsweft.com/zed): add a remote context server in Assistant settings.

## Verifying the install

Ask: **"What's in my Weft Backlog?"** The agent should call `list_tasks` (or
`get_board_state`) and answer with the board. On a brand-new account the
board is empty until `initialize_board` is called; "set up my Weft board"
does that.

An unauthenticated request is *supposed* to fail: the endpoint answers `401`
with a `WWW-Authenticate: Bearer resource_metadata=…` header, as MCP and
OAuth 2.1 require. That 401 is the discovery handshake, not a broken server.

## Troubleshooting

- **"Connection failed" right after adding the URL**: the OAuth window was
  closed before approval. Remove the server and add it again, or use an
  access token.
- **Tools list is empty**: the client cached an old session; disable and
  re-enable the server.
- **401 with a token**: the token was revoked or mistyped; create a new one.

## More

- Tool reference: https://letsweft.com/docs/mcp-tools
- All client guides: https://letsweft.com/integrations
- Overview for LLMs: https://letsweft.com/llms.txt
- Support: support@letsweft.com