Skip to content
Back to search

mcp

Web3alert's hosted MCP server for AI agents: decoded on-chain events delivered to your webhook. Docs and MCP Registry entry.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/web3alert--mcp/badge.svg)](/listings/web3alert--mcp)

HTML

<a href="/listings/web3alert--mcp"><img src="/api/listings/web3alert--mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 110 lines
  1. # Web3alert MCP server
  2. Decoded on-chain events for AI agents. Connect an MCP client to Web3alert's hosted server, find a trigger in the catalog of EVM and Substrate chains (Ethereum, Polkadot, Kusama and more), subscribe your webhook to it, and Web3alert sends each matching event to it as JSON, signed whenever the webhook has a signing secret (every new webhook gets one). Nothing to install: the server is hosted.
  3. | | |
  4. |---|---|
  5. | Endpoint | `https://web3alert.io/mcp/agent` |
  6. | Transport | Streamable HTTP, stateless |
  7. | Authentication | `initialize` and `tools/list` work without a token; tool calls need `Authorization: Bearer <personal access token>` |
  8. | MCP Registry | [`io.web3alert/agent`](https://registry.modelcontextprotocol.io/v0/servers?search=io.web3alert) |
  9. | Docs | [Agent quickstart](https://docs.web3alert.io/en/agents) · [MCP reference](https://docs.web3alert.io/en/mcp-server) · [Webhooks](https://docs.web3alert.io/en/webhooks) |
  10. This repository describes the server and holds its registry entry ([`server.json`](server.json)). The server's source code is not public.
  11. ## Connect
  12. 1. A person signs in at [web3alert.io](https://web3alert.io) and copies the personal access token from the account page. Agents cannot open their own accounts yet.
  13. 2. Point your MCP client at `https://web3alert.io/mcp/agent` and send the token in the `Authorization` header. The server accepts the token only in that header. You can list the tools without a token; a tool call without one gets HTTP `401` with instructions, and a wrong token gets `401` on every request.
  14. **Claude Code**: this reads the token without echoing it or keeping it in shell history. Claude Code saves the header in its user configuration, so treat that file as a secret.
  15. ```bash
  16. printf 'Web3alert token: ' && read -rs WEB3ALERT_TOKEN && echo && [ -n "$WEB3ALERT_TOKEN" ] && claude mcp add --scope user --transport http web3alert-agent https://web3alert.io/mcp/agent --header "Authorization: Bearer $WEB3ALERT_TOKEN"
  17. ```
  18. **VS Code** (`.vscode/mcp.json`, with `WEB3ALERT_TOKEN` in the VS Code process environment):
  19. ```json
  20. {
  21. "servers": {
  22. "web3alert-agent": {
  23. "type": "http",
  24. "url": "https://web3alert.io/mcp/agent",
  25. "headers": { "Authorization": "Bearer ${env:WEB3ALERT_TOKEN}" }
  26. }
  27. }
  28. }
  29. ```
  30. **Claude Desktop and Cursor**: see the [MCP reference](https://docs.web3alert.io/en/mcp-server) for the `mcp-remote` entry.
  31. ## Tools
  32. | Tool | What it does | Kind |
  33. |---|---|---|
  34. | `get_account` | Your account, tier, EUR wallet balance, tier limits, and subscription counts in the current workspace. | read |
  35. | `find_triggers` | Searches the published catalog and your workspace for triggers; paged with `cursor`. | read |
  36. | `get_trigger` | A trigger's runtime inputs, event fields and filterable fields: use it to learn which inputs a subscription must supply. | read |
  37. | `list_webhooks` | Webhook endpoints in the current workspace, with their signing status. | read |
  38. | `add_webhook` | Registers an HTTPS webhook endpoint and returns its signing secret once. | write |
  39. | `create_subscription` | Delivers one trigger to one webhook, with the trigger's required inputs and optional filter conditions. | write |
  40. | `list_subscriptions` | Subscriptions in the current workspace. | read |
  41. | `set_subscription_state` | Pauses or resumes a subscription. | write |
  42. | `remove_subscription` | Deletes a subscription and stops its delivery. | write |
  43. | `get_delivery_log` | Delivery history for the workspace or one subscription; paged with `cursor`. | read |
  44. Every tool declares an output schema, and a successful call returns `structuredContent`. A tool error returns `isError: true` with a JSON error (for example `subscription_limit_reached`, `not_found`, `rate_limited`) in its text content.
  45. A typical first session: `get_account` → `find_triggers` → `get_trigger` → `add_webhook` → `create_subscription` → `get_delivery_log`. To receive events you need a public HTTPS endpoint; `add_webhook` refuses a URL that carries a username or password.
  46. - `create_subscription` takes the trigger's required inputs and optional filter conditions. A create or a resume can succeed with `state: "blocked"` at the plan's subscription limit, so check that the returned `state` is `on` before you expect events. If a create got no reply, call `list_subscriptions` before retrying, or you may create a duplicate.
  47. - After a pause or removal, pending retries stop within about 10 seconds; an attempt already due in that window can still arrive.
  48. - `get_delivery_log` follows the plan of the first account with the `owner` role in the workspace (your own plan only when there is none), not necessarily your tier from `get_account`; on a plan without delivery history it returns `not_in_plan`, so treat the last step of the session as optional.
  49. Tools act on the account's current workspace, which you choose in the app. Adding a webhook, creating a subscription and reading delivery history need the `owner` or `admin` role in that workspace.
  50. ## What agents cannot do here
  51. Agents on this endpoint cannot author or change triggers, projects, templates or data sources; change billing, plans or payments; manage tokens; delete accounts or workspaces; block subscriptions; or manage resources other than webhook endpoints.
  52. People who build catalog triggers use the full authoring server at `https://web3alert.io/mcp` with the same token. Creating projects there needs a paid plan.
  53. ## What your webhook receives
  54. Each delivery is a JSON body whose `id` (`evt_…`) stays the same across retries and equals the `webhook-id` header. Every delivery carries `webhook-id` and `webhook-timestamp` headers; an endpoint that currently has a signing secret also gets `webhook-signature` per [Standard Webhooks](https://www.standardwebhooks.com/): `v1,` followed by the base64 HMAC-SHA256 of `webhook-id.webhook-timestamp.raw-body`, keyed with the base64-decoded part of the `whsec_…` secret.
  55. - On a signed endpoint, verify the signature against the raw body before parsing JSON, and reject a `webhook-timestamp` more than five minutes from your clock. If your receiver requires signatures, also reject unsigned deliveries. A secret change takes about 10 seconds to apply, and moving a project to another workspace removes the secrets of the webhooks that move with it; generate a new secret for those.
  56. - Delivery is at least once: deduplicate by `webhook-id`.
  57. - Answer with a `2xx` quickly: requests time out after 4 seconds by default. HTTP `429`, `5xx`, timeouts and network errors before a response are retried, waiting at least 5 s, 1 min, 10 min, 1 h and 6 h between attempts (at most six attempts; the minimum schedule alone spans about 7 hours 11 minutes, and an outage on Web3alert's side can delay or expire a retry). A failed delivery that cannot be queued for retry (the queue is full, or the queued record with its event data exceeds 256 KB) is not retried. Other responses end the delivery, redirects are not followed, and test deliveries are never retried.
  58. - An HTTP `410` blocks the subscription at once. Five consecutive undelivered events for the same subscription and webhook block it too.
  59. - Each plan limits the delivery rate per subscription; events beyond the plan's queue can be dropped (see the [limits page](https://docs.web3alert.io/en/limits)).
  60. The [Webhooks page](https://docs.web3alert.io/en/webhooks) has the payload, verification code in Node.js and Python, a test vector, and which responses are retried.
  61. ## Limits
  62. - Free: 5 active subscriptions to non-Free projects per account, across all workspaces; subscriptions to Free projects are exempt. Paid plans and their delivery-history retention are on the [limits page](https://docs.web3alert.io/en/limits).
  63. - A default budget of 120 tool calls per minute per account on each server process, shared by both MCP endpoints and all of the account's tokens. Over the budget, a tool returns `rate_limited` with `retryAfter` in seconds.
  64. ## Coming soon
  65. - Wallet sign-in, so agents can open their own accounts.
  66. - USDC top-ups over x402.
  67. - An inbox to catch up on missed events.
  68. ## For machines
  69. - [`/llms.txt`](https://web3alert.io/llms.txt): what Web3alert is for agents, in one page.
  70. - [`/api/openapi.json`](https://web3alert.io/api/openapi.json): the agent-facing REST API.
  71. - [`server.json`](server.json): the MCP Registry entry.
  72. ## Issues and support
  73. Issues in this repository are public. Never post a token, a signing secret, or a webhook URL that carries credentials. This repository holds documentation only, so pull requests that change the server cannot be accepted here.
  74. Report a security problem privately through this repository's **Security → Report a vulnerability**, not in an issue.
  75. ## License
  76. The text and examples in this repository are under the [MIT License](LICENSE). The Web3alert service is governed by its own terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.