Needwing Plugins MCP Server

Needwing plugins

Client plugins and registry metadata for Needwing — research, comparisons and recommendations with grounded evidence, served over the Model Context Protocol.

• Remote MCP endpoint installed by every plugin here: https://needwing.ai/mcp/trial (Streamable HTTP; MCP 2026-07-28 and the earlier initialize eras). It works for everyone: the browser approval step creates a trial account automatically, a person already signed in at needwing.ai approves their own account, and the Agent can create an account in chat (needwing_sign_up / needwing_verify)
• Alternative address: https://needwing.ai/mcp — the sign-in address for hosts that run their own OAuth sign-in; it is also the only address that accepts named API keys (afk_…, created on the website by verified accounts)
• Authentication: OAuth 2.1 (PKCE S256; CIMD/DCR) discovered automatically from the endpoint's 401 WWW-Authenticate resource metadata — every manifest here is header-free, so the client runs the OAuth flow on first use
• Caller tools (scope research): needwing_ask, needwing_status, needwing_reply, needwing_evidence, needwing_stop; conversation tools: needwing_contact, needwing_conversation, needwing_send, needwing_inbox, needwing_inbox_ack, needwing_close; account tools: needwing_account, needwing_sign_up, needwing_verify

Accounts

Every path starts with one question — Sign in · Create account · Try:

• Try — no account needed. The installed https://needwing.ai/mcp/trial connector starts a trial account in the browser approval window (invisible human check, plus a visible "Sign in instead" link).
• Create account — the person signs up in chat: the Agent asks for the email, shows the current Terms and Privacy, and the person confirms with a code from their own inbox. On MCP this is needwing_sign_up and needwing_verify.
• Sign in — for an existing account. Your Agent never opens Needwing pages; existing accounts sign in in your browser (the host's sign-in window on https://needwing.ai/mcp, a device code from any device, or a web session before reconnecting the trial address).

One account path — trial → limited → verified. It is always the same account; nothing is merged or moved.

needwing_account shows the current level, limits and next steps. A quota refusal reports and offers the next level; publishing a provider needs verified, which is one web sign-in.

This repository packages one plugin (needwing) for several clients plus the official MCP Registry entry (server.json).

Install

Claude Code (and Grok Build)

claude plugin marketplace add actionflow-team/needwing-plugins
claude plugin install needwing@needwing

or inside a session: /plugin marketplace add actionflow-team/needwing-plugins and /plugin install needwing@needwing. Grok Build reads Claude Code marketplaces, plugins and skills automatically (see xAI docs), so the same commands work there.

Codex

codex plugin marketplace add actionflow-team/needwing-plugins
codex plugin add needwing@needwing-plugins

Without plugins, add the remote server directly (OAuth: run codex mcp login needwing afterwards to sign in an existing account on the sign-in address; key: export NEEDWING_API_KEY first):

# ~/.codex/config.toml
[mcp_servers.needwing]
url = "https://needwing.ai/mcp/trial"
# Sign-in or named-key variant (named keys work only on /mcp):
# url = "https://needwing.ai/mcp"
# bearer_token_env_var = "NEEDWING_API_KEY"

Cursor

Open this one-click install link (generated by scripts/make-cursor-deeplink.mjs):

cursor://anysphere.cursor-deeplink/mcp/install?name=needwing&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbmVlZHdpbmcuYWkvbWNwL3RyaWFsIn0%3D

or paste into ~/.cursor/mcp.json:

{
  "mcpServers": {
    "needwing": {
      "url": "https://needwing.ai/mcp/trial"
    }
  }
}

For a named API key instead of OAuth, point the same entry at https://needwing.ai/mcp and add:

"headers": { "Authorization": "Bearer ${env:NEEDWING_API_KEY}" }

Gemini CLI

gemini extensions install https://github.com/actionflow-team/needwing-plugins

(or install from a local clone: gemini extensions install ./gemini-extension). The extension registers the needwing MCP server (httpUrl, OAuth discovery on first use) and loads GEMINI.md context with the Needwing research instructions. Named-key variant — point the needwing entry at https://needwing.ai/mcp and add "headers": {"Authorization": "Bearer YOUR_KEY"} to gemini-extension.json when installing from a local copy (named keys work only on /mcp).

Claude Code key variant

The bundled .mcp.json has no headers and installs the trial address, so Claude Code runs OAuth. To use a static named key instead (verified accounts; /mcp only), edit the installed needwing server (or a project .mcp.json) to:

{
  "mcpServers": {
    "needwing": {
      "type": "http",
      "url": "https://needwing.ai/mcp",
      "headers": { "Authorization": "Bearer ${NEEDWING_API_KEY}" }
    }
  }
}

${NEEDWING_API_KEY} is expanded from your environment (MCP docs); set it before starting Claude Code. Never commit a literal key.

Repository layout

.claude-plugin/marketplace.json      Claude Code marketplace (plugin "needwing")
.agents/plugins/marketplace.json     Codex repo marketplace
plugins/needwing/                    one plugin directory, all client manifests
  .claude-plugin/plugin.json         Claude Code manifest
  .codex-plugin/plugin.json          Codex manifest
  .cursor-plugin/plugin.json         Cursor manifest
  .mcp.json                          MCP server config (Claude Code + Codex)
  skills/needwing/SKILL.md           bundled Needwing skill (canonical copy)
gemini-extension/                    Gemini CLI extension (gemini-extension.json + GEMINI.md)
server.json                          MCP Registry entry (ai.needwing/needwing)
scripts/                             validate / sync-skill / make-cursor-deeplink
docs/                                sources, publishing runbook

npm test validates every manifest: JSON parsing, required fields per format, that every plugin manifest installs the fixed trial endpoint https://needwing.ai/mcp/trial, that server.json lists exactly the two remote addresses, that the bundled skill matches the hash in skills.lock.json (and the Homepage source when present), and that the Cursor deep link above re-encodes exactly. Requires Node.js ≥ 24, no dependencies.

The bundled skill is the canonical served skill (GET /api/connect/skill). Re-sync it after upstream changes with:

NODE_USE_ENV_PROXY=1 npm run sync-skill          # fetch from needwing.ai and update
node scripts/sync-skill.mjs --from-source        # offline: copy from the Homepage source tree

Links

• Guides page: https://needwing.ai/connect
• Privacy: https://needwing.ai/privacy — Terms: https://needwing.ai/terms
• Skill source: GET https://needwing.ai/api/connect/skill
• Wire contract: https://needwing.ai/v3/network/openapi.json

License

MIT for the plugin files in this repository. Needwing is a hosted service; using it is subject to the Needwing terms and privacy policy above.