Sui faucet

Sui Testnet

Sui Testnet MCP server

Connect an MCP-capable client — Claude, Codex, Cursor, Windsurf — to the Sui Testnet faucet over a single streamable-HTTP endpoint. The server exposes three tools: request testnet tokens, poll claim status, and check faucet reachability.

Endpoint
https://faucetme.pro/api/mcp
Transport
streamable HTTP
Project slug
sui-testnet

Setup

Pick a client. The endpoint is the same; only the registration syntax differs.

Claude CLI

claude mcp add --transport http faucetme-sui https://faucetme.pro/api/mcp

Then run /mcp to confirm it loaded.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "faucetme-sui": {
      "transport": "http",
      "url": "https://faucetme.pro/api/mcp"
    }
  }
}

Codex CLI

Append to ~/.codex/config.toml:

[mcp_servers.faucetme-sui]
transport = "http"
url = "https://faucetme.pro/api/mcp"

Cursor

Settings → MCP → add server:

{
  "name": "faucetme-sui",
  "transport": "http",
  "url": "https://faucetme.pro/api/mcp"
}

Windsurf

Add to MCP servers config:

{
  "faucetme-sui": {
    "command": null,
    "transport": "http",
    "url": "https://faucetme.pro/api/mcp"
  }
}

Available tools

Three tools mapped directly to the faucet workflow.

project_info

tool

Health check. Returns MCP / faucet API reachability and the security mode in effect.

Returns
{ projectName, apiReachable, securityMode }
Example response
{
  "projectName": "Sui",
  "apiReachable": true,
  "securityMode": "internal-token"
}

claim_tokens

tool

Queues a faucet claim for the given project and wallet via the internal API. Returns a requestId you can poll.

Parameters
projectSlugstring
Project slug, e.g. "sui".
walletAddressstring
Destination wallet address.
Returns
{ requestId, status }
Example response
{
  "requestId": "8b3e9c1a-…-9f12",
  "status": "queued"
}

get_claim_status

tool

Returns the normalized payout status for a previously created requestId.

Parameters
projectSlugstring
Project slug, e.g. "sui".
requestIdstring (uuid)
ID returned by claim_tokens.
Returns
{ status, txHash?, errorMessage? }
Example response
{
  "status": "confirmed",
  "txHash": "0xabc…dead",
  "errorMessage": null
}

Claim status values

Both claim_tokens and get_claim_status return one of:

queued
Request accepted, waiting for the dispatcher worker.
sent
Transaction broadcast to the network.
confirmed
Transaction included in a block. txHash available.
failed
Dispatch failed. errorMessage describes the reason.
unknown
State could not be determined yet. Retry.

Example session

After the server is registered, the full flow takes three steps.

  1. 1.
    Confirm the server is loaded
    List MCP servers in your client.
    /mcp
  2. 2.
    Ask the assistant to claim
    Agent calls claim_tokens({ projectSlug: "sui-testnet", walletAddress: "0xabc..." }).
    Claim 1 SUI for 0xabc... on project "sui-testnet"
  3. 3.
    Poll status until confirmed
    Agent calls get_claim_status(requestId) until status is confirmed or failed.
    What is the status of request <requestId>?

Security model

No key custody
The MCP server is a thin proxy in front of the internal faucet API. It never holds wallet keys.
Optional bearer auth
Pass authToken on any tool call; set MCP_AUTH_TOKEN on the server to enforce.
Idempotency
Each claim_tokens call generates a fresh idempotency key to avoid double-dispatch on retry.
Client IP attribution
cf-connecting-ip and x-forwarded-for are forwarded so rate limits attribute to the real caller.

Troubleshooting

"Bad Request: No valid session ID"
The client did not send an initialize request first. Re-register the server in your client.
Tool returns apiReachable: false
The internal faucet API is down or unreachable from the MCP container. Check the dashboard for an outage banner.
Status stuck on queued
Dispatcher worker is paused or the project hit a rate-limit window. Wait and re-poll get_claim_status.
Sui Testnet Faucet