MCP Quick Start

Connect an AI agent to your Web-Nothing app in under 5 minutes. This guide covers token creation, client configuration, and your first tool call.

Prerequisites

You must turn on Agent access for the app to use MCP — click Agent ON in the app toolbar (this also unlocks the /api/apps/{appId}/llms doc, which returns 404 while agent access is off). You do not need Live mode: a Dev-mode app gets a 30-day MCP trial (auto-started on first access), and going Live makes MCP access permanent.

Step 1: Create an Agent Token

1. Open your app in the Web-Nothing workspace.
2. Click the Agent ON button in the toolbar to enable agent access (required — without it the MCP endpoint and /llms doc both return 404). Going Live is optional (it makes the 30-day MCP trial permanent).
3. Click the MCP button that appears.
4. Under Agent Tokens you will see two buttons:
   • + App Token (blue) -- data CRUD on this app only. Use for agents that just need to read or write records.
   • + Platform Token (purple) -- workspace-level operations: list apps, create new apps from prompts, install templates, create cross-app workflows, manage API connectors.
5. Optional: tick Allow schema edits (advanced) before clicking a button if you want the agent to be able to add tables, fields, or UI components to your app. Off by default. (This is the only way to grant schema-edit scope — there is no headless/platform-token path to it.)
6. Copy the token immediately -- it starts with wn_ and is shown only once.

Which token do I need?

A Platform Token works on the platform endpoint (/api/mcp) and on the per-app endpoint (/api/apps/{id}/mcp) of any app you own. An App Token is scoped to the single app it was minted for. If you're building an agent that creates an app and then needs to populate it, a single Platform Token is enough.

Step 2: Configure Your MCP Client

Claude Code

Run this command in your terminal (replace {appId} and the token):

claude mcp add web-nothing \
  --transport http \
  https://web-nothing.vercel.app/api/apps/{appId}/mcp \
  -- --header "Authorization: Bearer wn_your_token_here"

For platform-level access (manage all apps):

claude mcp add web-nothing-platform \
  --transport http \
  https://web-nothing.vercel.app/api/mcp \
  -- --header "Authorization: Bearer wn_your_platform_token_here"

Claude Desktop

Add to your MCP configuration file (~/.claude/mcp.json or Claude Desktop settings):

{
  "mcpServers": {
    "web-nothing": {
      "url": "https://web-nothing.vercel.app/api/apps/{appId}/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer wn_your_token_here"
      }
    }
  }
}

Any HTTP-Capable Agent

The MCP endpoint accepts standard JSON-RPC over HTTP:

• Discovery: GET /api/apps/{appId}/mcp with Authorization: Bearer wn_...
• Execution: POST /api/apps/{appId}/mcp with JSON body

No special SDK required -- any HTTP client works.

Step 3: Test with a Tool Call

Discover available tools

curl -s https://web-nothing.vercel.app/api/apps/{appId}/mcp \
  -H "Authorization: Bearer wn_your_token" | jq '.result.tools[].name'

This returns tool names based on your app's data tables. The verb pattern is {app}_{verb}_{table} where verb is create / list / update / delete / get (the table name is used as-is, so a tasks table yields task_tracker_create_tasks, task_tracker_list_tasks, etc.). Always read the actual names from tools/list rather than guessing.

Tool scopes. A default App Token exposes the data tools (list / count / create / update / delete records). Schema-edit tools (those that add tables, fields, or UI components) require a token created with the Allow schema edits option ticked. If you call a schema-edit tool with a token that lacks the scope, you get a 403 with a "not in scope" message (e.g. Spec tool "spec:add_field" not in scope (requires spec:add_field or spec:*)). The auto-generated docs at /api/apps/{appId}/llms and /api/apps/{appId}/docs label which tools require this scope.

List records

curl -s -X POST https://web-nothing.vercel.app/api/apps/{appId}/mcp \
  -H "Authorization: Bearer wn_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "task_tracker_list_tasks",
      "arguments": { "limit": 5 }
    }
  }' | jq '.result.content[0].text | fromjson'

Create a record

curl -s -X POST https://web-nothing.vercel.app/api/apps/{appId}/mcp \
  -H "Authorization: Bearer wn_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "task_tracker_create_tasks",
      "arguments": { "title": "Hello from MCP!", "priority": 2, "done": false }
    }
  }' | jq '.result.content[0].text | fromjson'

Match your app's field types. Each create tool's arguments are derived from your app's actual columns. A number field (like a priority level of 1, 2, 3) expects a number, a boolean field expects true / false, and a text field expects a string. To see the exact field names and types your tool accepts, inspect the inputSchema from the discovery call in the previous step. Sending a value of the wrong type (for example "priority": "high" for a numeric field) returns a validation error.

Step 4 (Optional): Headless Live + Agent Toggle (Platform Tokens)

If you have a Platform Token, you can flip an app's isLive and agentEnabled flags without a logged-in browser session. This is useful for end-to-end agent flows that build an app via apps_create_from_spec and immediately make it Live -- no browser required.

New apps start with agent access OFF. Every freshly created app has agentEnabled: false by default, so it is not reachable via its per-app MCP endpoint until you turn it on. After apps_create_from_spec (or templates_install), call apps_set_lifecycle with agentEnabled: true (and agentAllowedActions) before minting or using a per-app token — otherwise per-app calls will be rejected. This is the one easy-to-miss step in a fully headless build → use → go-live flow.

There are two equivalent paths -- pick whichever fits your client:

MCP tool (recommended) -- apps_set_lifecycle. Self-describing inputSchema, same tools/call envelope as every other MCP tool:

curl -X POST https://web-nothing.vercel.app/api/mcp \
  -H "Authorization: Bearer wn_your_platform_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "apps_set_lifecycle",
      "arguments": {
        "appId": "{appId}",
        "isLive": true,
        "agentEnabled": true,
        "agentAllowedActions": ["*"],
        "agentRateLimit": 60
      }
    }
  }' | jq '.result.content[0].text | fromjson'

REST PUT (back-compat) -- works the same; same allowlist, same gates:

curl -X PUT https://web-nothing.vercel.app/api/apps/{appId} \
  -H "Authorization: Bearer wn_your_platform_token_here" \
  -H "Content-Type: application/json" \
  -d '{"isLive": true, "agentEnabled": true, "agentAllowedActions": ["*"], "agentRateLimit": 60}'

About agentAllowedActions: ["*"]. Wildcards are stripped server-side, so ["*"] is stored as an empty list [] — and an empty allow-list means all data tools are callable (the default). To restrict the agent, pass explicit action IDs (e.g. ["task_tracker_list_tasks", "task_tracker_create_tasks"]); to allow everything, send [] or omit the field. Either way the response echoes the stored value, so don't be surprised to see [] after sending ["*"].

Both paths accept only isLive, agentEnabled, agentAllowedActions, agentRateLimit. Other fields (spec, publicEnabled, publicHiddenFields, connectorBindings, etc.) are rejected -- use the dedicated MCP tools instead:

Cross-owner attempts return a generic App not found error (the same response as a non-existent app -- the token never confirms whether an appId exists for another user). The REST path uses HTTP 404; the MCP path uses JSON-RPC isError: true with the same "App not found" text. Cross-owner attempts are audit-logged on the server.

The live-app cap and row-scope safety rail that gate the workspace UI also apply here -- platform-token requests do not bypass any safety check.

What's Next

• Platform tools -- create, modify, and delete apps programmatically with a PLATFORM-scoped token
• Data tools -- list, count, create, update, and delete records in any of your app's data tables
• AI-readable docs -- every app auto-generates a plain-text description at /api/apps/{appId}/llms for agents that need context about your app
• MCP Integration Guide -- full reference for token management, platform tools, and security
• Workflows -- automate actions across apps when events happen
• Webhooks -- receive data from external services
• User Guide -- workspace, templates, settings, and more