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 header X-API-Token works too.
  • Tools: 8, listed in the tool reference.

Quick start

  1. 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.

  2. 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"
  3. 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.

ScopeWhat it allowsTools
Read Walls
walls:read
See walls and their items, get install code, check an installlist_walls, get_wall, get_install, verify_install, list_recent_items
Write Items
walls:write
Post items to wallspost_item
Manage Walls
walls:manage
Create walls and add domains to themcreate_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.

InputTypeDescription
wall_idrequiredstringWall 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.

InputTypeDescription
namerequiredstring1 to 100 characters.
layoutstringlist (default), grid, ticker, treemap, or map for a visitor globe.
domainsstring[]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.

InputTypeDescription
wall_idrequiredstringWall UUID from list_walls.
domainrequiredstringHostname 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.

InputTypeDescription
wall_idrequiredstringWall UUID from list_walls.
frameworkstringhtml (default), react, next, wordpress, shopify, webflow or other.
placementstringpage (default), footer, sidebar or header. Footer and header give a compact one-line version.
nounstringGlobe walls in a footer or header: what to call visitors, like readers.
site_urlstringThe 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.

InputTypeDescription
wall_idrequiredstringWall UUID from list_walls.
site_urlrequiredstringThe site the wall was installed on.
since_minutesinteger1 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.

InputTypeDescription
wall_idrequiredstringWall UUID from list_walls.
contentrequiredstring1 to 5,000 characters.
formatstringtext (default) or html. HTML may not contain scripts, iframes, styles, forms, event handlers or javascript: links.
metadataobjectFlat 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.

InputTypeDescription
wall_idrequiredstringWall UUID from list_walls.
limitinteger1 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_item counts toward your plan's daily update limit, the same as an update from your site. See the plans.
  • create_wall respects 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 Authorization and the value starts with Bearer .
  • 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_id isn't one of your walls. Have the agent call list_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/mcp in 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-remote bridge.

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.

Prefer plain HTTP? Everything here also works through the REST API.