Documentation

Start local. Keep control.

Guides to the WebMCPify Core workflow and Search’s capability discovery, AI summaries, and live website execution.

Install Core

npm install --global @improvisus/webmcpify-core

Discover

webmcpify discover --path /path/to/project

Generate

webmcpify generate --path /path/to/project --provider codex --method auto

Review

webmcpify review --path /path/to/project

Apply

webmcpify apply --path /path/to/project

Test

webmcpify test --path /path/to/project --url http://localhost:3000 --provider codex

Evaluate

webmcpify final-eval --path /path/to/project --url http://localhost:3000 --provider codex

Requirements

Node.js 18+, Git with an initial commit, and a compatible Chrome build for live WebMCP tests.

Provider adapters

Gemini, Antigravity, Claude Code, Codex and OpenCode; availability depends on the local environment.

Review boundary

Generated source remains a proposal until a person reviews and approves the exact patch.

Local MCP server

After the first release, run npx --package @improvisus/webmcpify-core webmcpify-mcp from the target repository; the workspace stays rooted there.

Outcome verification

A successful tool response is a claim. Core checks the application’s resulting state and preserves evidence.

Search companion

Set the app server's WEBMCPIFY_SEARCH_API_URL to the deployed Search service. Search returns tool contracts and site inventories. With authorized access and explicit consent, its sandboxed browser can call relevant read-only capabilities across matching websites and compose a sourced answer.

1. Capability search

Search matches your intent against indexed website tools and returns their descriptions, schemas, source websites, and verification information. It does not visit or call the websites. Anonymous API/MCP clients can use discovery without a key by setting summarize: false and execute: false.

2. Capability summary

AI explains what the matching indexed capabilities offer and how they relate to your request. It uses the capability descriptions, rather than calling the tools. An indexed catalog-search capability can be described, but this mode does not establish the store’s current stock or prices. Use summarize: true and execute: false, or turn on Capability summary in the web interface.

3. Live execution and live AI summary

With Live AI answer enabled, Search uses its sandboxed browser to visit matching websites and invoke their relevant WebMCP tools. These are registered tool calls, rather than automated clicks through the page. AI then combines successful tool results into an answer, preserving sources and returned links; comparisons can include structured tables when the returned evidence supports them.

Find relevant indexed capabilities, including multiple tools and websites when appropriate.
Check permissions, verification, relevance, site scope, and read-only eligibility. Rediscover each tool on the live page and validate its exact contract and arguments before calling.
Call eligible tools within the request’s result limit and time budget. Missing inputs, unavailable tools, and failed or skipped calls are reported alongside successes.
Compose a summary from successful recorded results. A fresh call means current data returned by that website; it does not guarantee that the website’s underlying information is complete or up to date.

Use execute: true only when the user explicitly requests live execution. This uses the live summary mode; a separate capability summary is not generated first. Unrelated tools, changes to website data, and calls requiring invented inputs are not authorized by this switch. When nothing eligible succeeds, Search reports that limitation instead of presenting indexed descriptions as live evidence.

{
  "query": "Tell me about Improvisus",
  "limit": 10,
  "summarize": true,
  "execute": true
}

This input works with search_webmcp_capabilities over MCP or POST https://search.improvisus.tech/api/search with a JSON body. API/MCP summaries require an authorized key with search:read and search:ai; live execution additionally requires search:execute and a ready browser. The web interface uses its authorized app connection when configured.

See the connection guide below to request a key or connect an agent. Basic discovery remains available without a key.

Connect your agent

Use Search through API or MCP

Add this remote server to your MCP client. No local Search installation or browser extension is required; live website calls run in the Search service’s browser.

Capability search: Find indexed tools and inspect their contracts. No API key or live website calls are needed.
Capability summary: AI explains matching indexed tools; it does not fetch current website data.
Live AI summary: With explicit consent, Search calls relevant eligible read-only tools on their actual websites and summarizes the returned data with sources and per-tool outcomes.

AI access through API/MCP requires a requested agent key. Both AI modes are also available in web search when its authorized connection is ready. How summaries and live execution work →

Server URL

https://search.improvisus.tech/mcp

Transport: Streamable HTTP. Choose a remote HTTP server in your client, paste the URL, then connect and list its tools.

1. Connect your client
With Claude Code installed, run this in your terminal. The user scope makes the connection available across your projects. No Search API key is needed for discovery.
claude mcp add --transport http --scope user webmcpify-search https://search.improvisus.tech/mcp
Run claude mcp get webmcpify-search to inspect the configuration. Inside Claude Code, use /mcp to check the connection and available tools.
With an AI access key (optional)
Once you receive a key, update the server entry in your private ~/.claude.json user configuration. Replace the placeholder with your own key and keep that file private.
{ "mcpServers": { "webmcpify-search": { "type": "http", "url": "https://search.improvisus.tech/mcp", "headers": { "Authorization": "Bearer YOUR_AGENT_KEY" } } } }
Claude Code connection guide ↗
With OpenAI Codex CLI installed, add the remote server. This uses your local Codex configuration, shared with the IDE extension. No Search API key is needed for discovery.
codex mcp add webmcpify-search --url https://search.improvisus.tech/mcp
Run codex mcp list, then start a new Codex session and use /mcp to check the connection and tools. Restart the IDE extension if it was already open.
With an AI access key (optional)
Once you receive a key, update the existing server entry in ~/.codex/config.toml to read it from an environment variable:
[mcp_servers.webmcpify-search] url = "https://search.improvisus.tech/mcp" bearer_token_env_var = "WEBMCPIFY_SEARCH_AGENT_KEY"
Replace the placeholder below with your key and start Codex from that terminal. For the IDE extension, make the variable available to the process launching your editor.
export WEBMCPIFY_SEARCH_AGENT_KEY="YOUR_AGENT_KEY" codex
This is a WebMCPify agent key, not an OpenAI API key. Leave the bearer-token setting out when using anonymous discovery.
OpenAI Codex MCP guide ↗
For another MCP client, use its remote server settings with the same URL and transport.
2. Choose your access
Discovery is public. No key is needed to find capabilities or inspect their contracts. For discovery-only searches, explicitly set summarize: false and execute: false.
Request a key for AI capability summaries and live AI answers through the API or MCP. Add this custom header in your client, replacing the placeholder with your own key:
```
Authorization: Bearer YOUR_AGENT_KEY
```
Summary access needs search:read and search:ai; live answers also need search:execute. Request an agent key if you do not have one.
Both summary modes are also available in web search. Choose Capability summary to explain indexed tools, or Live AI answer to call eligible website tools and summarize their current results. The web app uses its authorized connection when available; you do not need to paste a personal agent key into the page.
3. Make your first search
Ask your agent: “Use WebMCPify Search to tell me about Improvisus. Discover matching capabilities only; do not generate a summary or call website tools.”
The agent calls search_webmcp_capabilities with:
```
{
  "query": "Tell me about Improvisus",
  "limit": 10,
  "summarize": false,
  "execute": false
}
```
For an indexed AI summary, set summarize: true. For an explicitly requested live answer, set execute: true: Search calls eligible read-only tools on the matching websites and returns a sourced answer plus each tool outcome. Keys and quotas still apply; unrelated or ineligible tools are not executed.

The four MCP tools and when to use them

search_webmcp_capabilities: Search by intent. Accepts query, limit (default 10, maximum 50), summarize, execute, and optional verification/action filters.
get_webmcp_capability: Inspect an exact tool contract using a capabilityId returned by search.
list_site_webmcp_capabilities: Inspect a site’s indexed inventory using its siteId; this does not call those website tools.
get_webmcp_site: Read site identity, source, freshness, and verification details using its siteId.

Having trouble? Use the full HTTPS URL ending in /mcp. For a 401/403 response, check your key, expiry, scopes, and whether AI was requested. For 429, wait for the limit to reset. A connected MCP client can still discover capabilities when live execution is unavailable.

Guard developer preview

Inspect live WebMCP tools locally.

Guard Inspector discovers tools registered on the current page, reviews their schemas and safety hints, validates test arguments, and supports one controlled manual call. Paste mode remains available for offline descriptor audits. Inspector data stays in the browser.

Open Guard Inspector →