VitalWall MCP server
VitalWall runs a remote MCP (Model Context Protocol) server, so an AI agent can work with your walls the way you do. It can list and create walls, post items that show up live everywhere the wall is embedded, read what is on a wall, and get the exact code to add a wall to a site, then check that it works.
- Address:
https://vitalwall.com/mcp - Transport: Streamable HTTP (JSON-RPC over POST). There is no SSE endpoint.
- Auth: a VitalWall API token in the header
Authorization: Bearer vw_live_…. The headerX-API-Tokenworks too. - Tools: 8, listed in the tool reference.
Quick start
- Create a token.
Go to API Tokens in your account and choose Generate New Token. Give it Read Walls and Write Items, and add Manage Walls if the agent should create walls or add domains. The token starts with
vw_live_and is shown once, so copy it before you close the dialog. - Add the server to your client. In Claude Code it is one command. Every other client has its own page below.
claude mcp add --transport http vitalwall https://vitalwall.com/mcp \ --header "Authorization: Bearer YOUR_VITALWALL_TOKEN" - Ask your agent for something. For example: “List my VitalWall walls, then post ‘Hello from my agent’ to the first one.” The item appears on the wall right away.
Set up your client
Windsurf
In Cascade, open the MCP menu and choose Open MCP config file (~/.codeium/windsurf/mcp_config.json). Add the server, set VITALWALL_TOKEN in your environment, and refresh the server list.
{
"mcpServers": {
"vitalwall": {
"serverUrl": "https://vitalwall.com/mcp",
"headers": {
"Authorization": "Bearer ${env:VITALWALL_TOKEN}"
}
}
}
}OpenAI Codex
Add this to ~/.codex/config.toml and export VITALWALL_TOKEN before you start Codex. Check it with codex mcp list, or /mcp inside Codex.
[mcp_servers.vitalwall]
url = "https://vitalwall.com/mcp"
bearer_token_env_var = "VITALWALL_TOKEN"Any other MCP client
Any client that supports remote servers over Streamable HTTP with a custom header can connect. Most take a config like this one. If yours only starts local servers, use the mcp-remote bridge shown on the Claude Desktop page.
{
"mcpServers": {
"vitalwall": {
"type": "http",
"url": "https://vitalwall.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_VITALWALL_TOKEN"
}
}
}
}Tool reference
Agents usually call list_walls first to get a wall_id. Each tool needs one of the token's scopes. The server says which scope is missing when a call is refused.
| Scope | What it allows | Tools |
|---|---|---|
| Read Walls walls:read | See walls and their items, get install code, check an install | list_walls, get_wall, get_install, verify_install, list_recent_items |
| Write Items walls:write | Post items to walls | post_item |
| Manage Walls walls:manage | Create walls and add domains to them | create_wall, add_wall_domain |
list_walls
Lists your walls with their IDs, layout, allowed domains and whether the wall hit its daily update limit. Agents call it first to get a wall_id. Needs the Read Walls scope. Read only.
No inputs.
Example arguments:
{}Returns: { "walls": [{ "id": "…", "name": "Launch wall", "active": true, "layout": "list", "domains": ["example.com"], "daily_limit_reached": false, "created_at": "…" }] }
get_wall
One wall's settings, its wall API key and its plain-HTML embed snippet. Needs the Read Walls scope. Read only.
| Input | Type | Description |
|---|---|---|
wall_idrequired | string | Wall UUID from list_walls. |
Example arguments:
{
"wall_id": "8f0c2c1e-1b2a-4c3d-9e8f-123456789abc"
}Returns: The wall summary plus display_limit, api_key and embed_html.
create_wall
Creates a wall. Respects your plan's wall limit. Use layout map for a live visitor globe. Needs the Manage Walls scope.
| Input | Type | Description |
|---|---|---|
namerequired | string | 1 to 100 characters. |
layout | string | list (default), grid, ticker, treemap, or map for a visitor globe. |
domains | string[] | Hostnames allowed to show and post to the wall, like ["example.com"]. |
Example arguments:
{
"name": "Deploys",
"layout": "ticker",
"domains": [
"example.com"
]
}Returns: { "created": true, "wall": { … }, "embed_html": "…", "next_step": "…" }
add_wall_domain
Lets a website show and post to a wall. Needed before a wall works on a new site. Safe to call twice. Needs the Manage Walls scope.
| Input | Type | Description |
|---|---|---|
wall_idrequired | string | Wall UUID from list_walls. |
domainrequired | string | Hostname or URL, like example.com or https://www.example.com. |
Example arguments:
{
"wall_id": "8f0c2c1e-1b2a-4c3d-9e8f-123456789abc",
"domain": "example.com"
}Returns: { "wall_id": "…", "domains": ["example.com"], "added": true }
get_install
The exact code to add a wall to a site and where it goes, for the site's platform and the spot on the page. Also says how the site sends items to the wall. Needs the Read Walls scope. Read only.
| Input | Type | Description |
|---|---|---|
wall_idrequired | string | Wall UUID from list_walls. |
framework | string | html (default), react, next, wordpress, shopify, webflow or other. |
placement | string | page (default), footer, sidebar or header. Footer and header give a compact one-line version. |
noun | string | Globe walls in a footer or header: what to call visitors, like readers. |
site_url | string | The site the wall goes on. Checks that the wall allows that domain. |
Example arguments:
{
"wall_id": "8f0c2c1e-1b2a-4c3d-9e8f-123456789abc",
"framework": "next",
"placement": "footer",
"site_url": "https://example.com"
}Returns: The steps (title, where, code), notes, and a domain_check when site_url is given.
verify_install
Checks that a wall is set up for a site: whether the site's domain is allowed and whether updates from it arrived in the time window. Needs the Read Walls scope. Read only.
| Input | Type | Description |
|---|---|---|
wall_idrequired | string | Wall UUID from list_walls. |
site_urlrequired | string | The site the wall was installed on. |
since_minutes | integer | 1 to 10080. Default 60. |
Example arguments:
{
"wall_id": "8f0c2c1e-1b2a-4c3d-9e8f-123456789abc",
"site_url": "https://example.com"
}Returns: { "status": "live" | "waiting" | "domain_not_allowed", "latest_update": { … }, "next_step": "…" }
post_item
Posts text or simple HTML to a wall. It shows up on every place the wall is embedded, in real time. Counts toward your plan's daily update limit. Needs the Write Items scope.
| Input | Type | Description |
|---|---|---|
wall_idrequired | string | Wall UUID from list_walls. |
contentrequired | string | 1 to 5,000 characters. |
format | string | text (default) or html. HTML may not contain scripts, iframes, styles, forms, event handlers or javascript: links. |
metadata | object | Flat key/value data (strings, numbers, booleans), up to 20 keys and 2 KB. |
Example arguments:
{
"wall_id": "8f0c2c1e-1b2a-4c3d-9e8f-123456789abc",
"content": "Deploy finished: v2.4.1 is live",
"metadata": {
"env": "production"
}
}Returns: { "posted": true, "item_id": "…", "wall_id": "…" }
list_recent_items
The latest items on a wall, newest first. Needs the Read Walls scope. Read only.
| Input | Type | Description |
|---|---|---|
wall_idrequired | string | Wall UUID from list_walls. |
limit | integer | 1 to 50. Default 10. |
Example arguments:
{
"wall_id": "8f0c2c1e-1b2a-4c3d-9e8f-123456789abc",
"limit": 10
}Returns: { "wall_id": "…", "items": [{ "id": "…", "content": "…", "format": "text", "created_at": "…" }] }
Limits
- Every
post_itemcounts toward your plan's daily update limit, the same as an update from your site. See the plans. create_wallrespects your plan's wall limit.- An item's content is 1 to 5,000 characters. Metadata is flat, up to 20 keys and 2 KB.
- HTML items can't contain scripts, iframes, styles, forms, event handlers or javascript: links.
- A wall allows up to 20 domains.
Troubleshooting
- Missing API token. The client sent no token. Check the header name is
Authorizationand the value starts withBearer. - Invalid token format. The value isn't a VitalWall token. It should start with
vw_live_. A wall's API key won't work here. - Invalid, expired or revoked token. Make a new token on the API tokens page and update your client.
- Missing the scope needed for a tool. The token doesn't have that tool's scope. Tokens can't be changed, so create one with the scopes in the table above.
- Wall not found. The
wall_idisn't one of your walls. Have the agent calllist_walls. - Daily update limit reached. The wall hit your plan's limit for today. It resets daily, or you can upgrade.
- Method not allowed (405). Opening
https://vitalwall.com/mcpin a browser sends a GET, and the server only takes POST. That response means the server is up. - The client can't connect at all. Make sure it supports remote servers over Streamable HTTP. Older clients that only speak SSE need the
mcp-remotebridge.
To test a token without a client, list the tools with curl:
curl -s https://vitalwall.com/mcp \
-H "Authorization: Bearer YOUR_VITALWALL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'FAQ
Can I connect ChatGPT or Claude on the web?
Not yet. Those apps connect to remote servers through OAuth sign-in, and the VitalWall MCP server takes API tokens for now. Clients where you can set a header, like the ones above, all work.
Is the token safe to put in a config file?
Treat it like a password. Use an environment variable or your client's secret prompt where it has one, keep it out of files you commit, and give each agent its own token with only the scopes it needs. You can revoke a token any time on the API tokens page.
What can an agent do with it?
Post deploy notices, show what a team of agents shipped, add a live visitor globe to a site, or read the latest items back. See the examples.
