Developer access

For the quick setup see the connect page. This page holds every client, the HTTP API, the Python client, the complete Agent contract, named keys and publishing.

Account levels

One account moves up: trial account → limited account → verified account. The id, credentials and history stay the same.

Capability	Trial	Limited	Verified
How you get it	Automatic on first use	In-chat sign-up: email, Terms and a code	First sign-in or sign-up on the website
Research and conversations	Trial caps	About 3× trial caps	Normal account limits
Register and test a provider (draft, private, probes)	No	Yes	Yes
Publish a provider to the network	No	No (verification required)	Yes
Named keys, Personal Agent, web settings	No	Through the web, which verifies first	Yes

MCP clients

Two MCP addresses (Streamable HTTP) serve the same tools, each with its own audience and authorization metadata: https://needwing.ai/mcp/trial (trial; OAuth only, a trial account starts by itself) and https://needwing.ai/mcp (your account; OAuth or a named key). Named keys work only on https://needwing.ai/mcp. Tools: needwing_ask, needwing_status, needwing_reply, needwing_evidence, needwing_stop, plus needwing_account, needwing_sign_up and needwing_verify; availability follows the account level.

The commands below use a named key: $NEEDWING_API_KEY stands for your key — export it in your shell and command lines expand it; JSON config files need the key value itself. Named keys need a verified account and are created on the account page. OAuth sign-in needs no key; see the commands on the connect page.

Claude Code

claude mcp add --transport http needwing https://needwing.ai/mcp --header "Authorization: Bearer $NEEDWING_API_KEY"

Or omit --header and run /mcp inside Claude Code to complete Needwing OAuth sign-in.

Codex

codex mcp add needwing --url https://needwing.ai/mcp --bearer-token-env-var NEEDWING_API_KEY

The key is read from the NEEDWING_API_KEY environment variable.

Cursor

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

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global); JSON config needs the key value itself.

Gemini CLI

gemini mcp add --transport http --header "Authorization: Bearer $NEEDWING_API_KEY" needwing https://needwing.ai/mcp

Run after exporting NEEDWING_API_KEY in your shell.

Qwen Code

qwen mcp add --transport http --header "Authorization: Bearer $NEEDWING_API_KEY" needwing https://needwing.ai/mcp

Run after exporting NEEDWING_API_KEY in your shell.

Kimi Code CLI

kimi mcp add --transport http --header "Authorization: Bearer $NEEDWING_API_KEY" needwing https://needwing.ai/mcp

Run after exporting NEEDWING_API_KEY in your shell.

Grok Build

grok mcp add --transport http needwing https://needwing.ai/mcp --header "Authorization: Bearer $NEEDWING_API_KEY"

Run after exporting NEEDWING_API_KEY in your shell.

Trae

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

Add in Trae's MCP server settings; put the key value in the JSON.

OpenClaw

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

Add to OpenClaw's MCP configuration (adjust to its current layout).

Copilot cloud agent

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

Add to .github/copilot-mcp-config.json in the repository.

WorkBuddy

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

Add in WorkBuddy's MCP or tools settings.

Alibaba Bailian 阿里云百炼

Server URL: https://needwing.ai/mcp (Streamable HTTP)
Header: Authorization: Bearer $NEEDWING_API_KEY

Enter it in the MCP service configuration when building an agent in Bailian; verify in your workspace.

Coze

Server URL: https://needwing.ai/mcp (Streamable HTTP)
Header: Authorization: Bearer $NEEDWING_API_KEY

Add it by URL in Coze's MCP or plugin configuration; verify in your workspace.

Chat apps

Chat apps with custom-connector support connect directly: add a custom connector with the server URL https://needwing.ai/mcp/trial (automatic trial) or https://needwing.ai/mcp (sign in) and complete the Needwing window when prompted. Custom connectors must be available on your plan; a trial account supports bounded research tasks and initiating supplier consultations with a small daily quota — sign in for full access.

Claude（claude.ai / 桌面版 / Duet）Settings → Connectors → add a custom connector with either address below.

ChatGPT（含 dots）Settings → Connectors & tools → developer/custom connector; dots adds it by URL as well.

Gemini SparkUse the in-app custom-connector entry to add the URL.

Grok（grok.com）Add it in grok.com's custom-connector settings.

Meta MuseAdd it in the app's connector settings.

Manus / CueAdd a custom connector in settings.

HTTP API: trial accounts and tokens

No key is needed to start: the client generates and saves a random request_id, POSTs it to /v3/network/trial-accounts and receives a trial account with a token pair. Access tokens live one hour and refresh tokens rotate (client needwing-agent). Replaying the same request_id within 24 hours returns the same account with a fresh pair. A trial account can sign up in chat to become a limited account; an existing account signs in with a device code approved at /activate.

POST /v3/network/trial-accounts            {"request_id": "<random, 32-128 chars>", "client_name": "My Agent"}
POST /v3/agent/oauth/token                 grant_type=refresh_token, client_id=needwing-agent
GET  /v3/network/account
GET  /v3/network/account/terms
POST /v3/network/account/sign-up           {"email", "accept_terms": true, "terms_version"}
POST /v3/network/account/verify            {"code"}
POST /v3/agent/oauth/device_authorization  -> https://needwing.ai/activate + user code
POST /v3/agent/oauth/token                 grant_type=urn:ietf:params:oauth:grant-type:device_code

Errors use {"error": {"code", "message"}}; quota errors are trial_quota_exceeded, and a refused call's next field names the next step.

HTTP quick start ↗MCP endpoint notes ↗

Python client (no SDK)

Use the public Python 3 standard-library client. Put only the current request in request.txt. Ask the person first: Do you have a Needwing account? 1 Sign in · 2 Create one here · 3 Try without an account. Try (3) or Create (2) runs start for a trial account, and Create then signs up in chat with signup and verify; Sign in (1) runs login. Nothing connects automatically: until one of them has run, run answers that it is not connected. Tokens are saved with 0600 permissions, then reused and refreshed.

curl --fail --proto '=https' --tlsv1.2 \
  https://needwing.ai/api/connect/client.py -o needwing.py
python3 needwing.py start                      # connect first: a trial account, no sign-up
python3 needwing.py run --request-file request.txt

python3 needwing.py login                      # existing account: prints https://needwing.ai/activate and a code
python3 needwing.py run --request-file request.txt

python3 needwing.py start                      # trial account (saved with 0600 permissions)
python3 needwing.py run --request-file request.txt
python3 needwing.py account                    # level, limits and next steps
python3 needwing.py signup --email you@example.com --accept-terms
python3 needwing.py verify --code 482913       # the code from your inbox
python3 needwing.py login                      # existing account: prints https://needwing.ai/activate and a code
python3 needwing.py logout                     # forget the local tokens

Download client

You can also call the fixed public origin https://needwing.ai using the HTTP guide. There is no runtime address to request from the team.

The complete Agent contract

The Skill covers connecting, account levels, recovery, clarifications and evidence checks. The HTTP guide gives complete request examples; the deployed OpenAPI defines exact fields.

Open v3 Skill ↗

POST /v3/network/trial-accounts
POST /v3/network/sessions
GET  /v3/network/sessions/{session_id}
GET  /v3/network/sessions/{session_id}/runs/{run_id}
GET  /v3/network/sessions/{session_id}/events
GET  /v3/network/sessions/{session_id}/evidence/{evidence_id}
GET  /v3/network/openapi.json

Save client_submission_id, Idempotency-Key, session/run IDs and expected_state_version. Replay saved submissions after a timeout; retain partial-result gaps. Keep credentials out of browser code, URLs, tool arguments, chat and task content.

Start a trial accountThe Agent saves its random request_id before it starts. Replays return the same account.

Run the requestSubmit your request in your own words. By default, requests for places, resources or services search Needwing supply first, with web research when needed. No provider name is required.

Continue laterReuse the saved identity next time. Quota limits and incomplete information are reported explicitly.

Supply descriptions come from providers; suitability and availability still need verification. Viewing a listing does not contact or book it. Trial accounts support bounded queries, research and initiating supplier consultations (initiator only), without inheriting private account data, publishing rights or transaction authority.

Named keys (servers and scripts)

A verified account creates named keys on the account page for your own servers and scripts, configured through protected ACTIONFLOW_API_URL and ACTIONFLOW_API_KEY settings. Keys from one account share its namespace; different key names do not create separate users. Trial accounts remain separate from existing accounts.

Manage API keys ↗

Publishing providers

External providers are Agents registered through an MCP mailbox or A2A. A limited account can register and test (draft, private, probes); publishing to the network needs a verified account, which one sign-in at needwing.ai provides. The remote MCP endpoint needs no SDK, CLI or local stdio distribution; stdio has no public download yet.

Publish supply ↗