You ask an AI assistant a useful question, then copy information from three other apps so it can answer. A connected tool can remove some of that copying. The assistant asks a defined function for current information, receives a result, and uses it in the conversation.

In this lesson you will first learn to use an existing MCP connection. Then you will build a small server that searches a fictional workshop catalog, connect it to an assistant, and expose the same kind of search through a webpage. You do not need to create a paid product or share an API key to complete the lab.

What you will make

  • A local Python MCP server with one read-only tool.
  • A protocol test that checks real client/server communication.
  • A simple webpage with a normal search form and optional WebMCP support.
  • A tool contract and pilot worksheet you can adapt to a real task.

Allow time to set up Python and a compatible editor if they are new to you. Complete the connection walkthrough first if you do not want to code yet. The provider examples explain why this is useful; the workshop catalog makes the mechanics concrete.

MCP and WebMCP: what each one does

When people say “use an MCP,” they usually mean connect an AI assistant to an MCP server. Model Context Protocol gives an AI application a structured way to discover and call tools, read resources and use reusable prompts. The server is the program that exposes those capabilities; it may run locally or at a remote URL. It can wrap an API you already have.

WebMCP is a browser API proposal for tools exposed by the current webpage. The browser agent can ask for a named action with structured inputs instead of inferring every step from buttons, screenshots or page markup. It is useful when the open page and its session are part of the job. You can build a WebMCP tool without deploying a remote MCP server.

NeedStart withExample
Work across applicationsMCP serverLook up approved project information from an assistant.
Act in an open webpageWebMCPSearch the page’s catalog or select an available option.
Connect ordinary software servicesExisting APIApply your application’s business rules and permissions.
Delegate between independent agentsAn agent-to-agent protocolCoordinate separate agents; this is a different layer.

Neither protocol grants extra account access. Tool names and annotations describe behavior; your application still has to enforce it. Keep pricing, eligibility, access control and validation in the same business logic used by the ordinary product.

MCP connects an AI application to a server. WebMCP exposes tools in an open webpage. Both reuse application permissions.
MCP connects an AI application to a server. WebMCP exposes tools in an open webpage. Both reuse application permissions.

Use an existing MCP: four steps

  1. Choose a narrow job. Write a request with an observable result, such as “find the three approved documents about onboarding and return their source links.” Start with information you can independently verify.
  2. Find the official connection. Follow the provider’s own setup page. A remote integration generally supplies a URL and may use an account authorization flow. A local server supplies a launch command and runs on your computer. A directory entry alone is not proof that a package is the provider’s official software.
  3. Review what it can do. Check the connected account and workspace, available tools, requested permissions and whether the assistant requires confirmation for changes. Use the narrowest useful access. Keep credentials in the host’s supported secret settings, not in prompts or public configuration files.
  4. Ask, inspect and verify. Run one read-only request. Compare the tool result with the original application. Record missing data, errors and which account was searched before moving to edits or automation.
Use the connected tool to find information about [topic]. Return the source links and the exact result. Separate missing information from facts. Do not change records or send messages.

If tools do not appear, check that your assistant supports the server’s transport, the connection is enabled, authorization has finished and your account has the required access. For local servers, check executable paths and logs. A successful connection is only the first test; the requested task still has to work.

Connect in four steps: choose the job, connect the official server, run a read-only request, and verify the result.
Connect in four steps: choose the job, connect the official server, run a read-only request, and verify the result.

Create an MCP server: start with one useful tool

You are building an adapter around a real capability. Define the contract before choosing a framework: what is the tool called, what input does it accept, what does success return, who may use it, and what happens when it fails?

The example tool contract specifies intent, inputs, execution, results and verification before implementation.
The example tool contract specifies intent, inputs, execution, results and verification before implementation.
  1. Choose one read-only function. Our example searches two fictional workshops. It has no account credentials and cannot book, publish or charge anything.
  2. Describe inputs and outputs precisely. A topic is a nonempty string of up to 80 characters. Results contain stable workshop IDs and a demo: true marker. A valid search with no matches returns an empty array; invalid input returns an error.
  3. Register the function with an official SDK. The Python example in the starter kit uses FastMCP from the official mcp package’s v1 line. This is different from installing a separate package named fastmcp.
  4. Test discovery and execution. A tool that imports successfully may still fail when a client calls it. Exercise the actual protocol, including errors, before connecting an assistant.
  5. Connect a compatible host. Supply the absolute Python executable and server file paths. The host launches the local process and communicates over standard input/output, or stdio.
  6. Replace demo data deliberately. Integrate one real API, enforce user authorization, bound result sizes, set timeouts and return clear errors. For remote distribution, use Streamable HTTP and appropriate authentication; do not expose this unauthenticated local lab on the public internet.

Step 1 — Create an isolated Python environment

This reproducible lab uses Python 3.11+ and mcp[cli]==1.29.0, the version used in our transport tests. SDK v2 uses different APIs; do not mix the code below with an unpinned v2 installation. For a new production project, review the current v2 documentation and migration guide.

# macOS / Linux, with Python 3.11 or newer installed
mkdir mcp-workshop-lab
cd mcp-workshop-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "mcp[cli]==1.29.0"

On Windows PowerShell, use py -m venv .venv and activate with .venv\Scripts\Activate.ps1. If activation is restricted, run .venv\Scripts\python.exe directly. No AI API key is needed for this demo server.

Step 2 — Save this as workshop_server.py

"""A read-only MCP teaching server. All workshops are fictional demo data."""
from mcp.server.fastmcp import FastMCP
from mcp.types import ToolAnnotations

mcp = FastMCP("Workshop Finder")
WORKSHOPS = [
    {"id": "intro-ai", "title": "Introduction to AI", "level": "beginner"},
    {"id": "build-mcp", "title": "Build an MCP server", "level": "intermediate"},
]

@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
def find_workshops(topic: str) -> dict[str, object]:
    """Search fictional workshop titles. Returns matches; never books a place."""
    if not topic.strip() or len(topic) > 80:
        raise ValueError("Use a topic between 1 and 80 characters.")
    query = topic.strip().casefold()
    return {"demo": True, "workshops": [
        item for item in WORKSHOPS if query in item["title"].casefold()
    ]}

if __name__ == "__main__":
    mcp.run(transport="stdio")

The description tells the assistant what the tool does. The type annotation helps generate the schema. The read-only hint describes behavior; it does not enforce security. Keep diagnostic logging on stderr because stdout is the protocol channel for a stdio server.

Step 3 — Run the included protocol test

Download and extract the starter kit into this folder. It includes test_workshop_server.py, which launches the server, discovers the tool, calls it and checks its results.

python test_workshop_server.py

Expected result: a PASS message covering discovery, matching, normalization, no matches and invalid input. Optional: with Node.js and npm installed, run mcp dev workshop_server.py to inspect the server interactively. Running python workshop_server.py alone waits for a client on stdin; a quiet terminal is expected.

Step 4 — Connect it to VS Code

Create .vscode/mcp.json with the configuration below. Replace both placeholder paths with actual absolute paths. On Windows the executable is .venv/Scripts/python.exe; JSON paths can use forward slashes. Start the server from VS Code’s MCP server controls, review the trust prompt, and use a tool-capable agent session.

{
  "servers": {
    "workshops": {
      "type": "stdio",
      "command": "/ABSOLUTE/PATH/mcp-workshop-lab/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/mcp-workshop-lab/workshop_server.py"
      ]
    }
  }
}

Ask: “Use find_workshops to search for AI. Show the workshop ID and title. This is demo data; do not book anything.” Expect intro-ai and Introduction to AI. Other MCP hosts have their own configuration format; do not assume VS Code’s servers wrapper is interchangeable with another host’s settings.

Step 5 — Try the edge cases

InputExpected outcome
AIThe intro-ai workshop.
MCPThe build-mcp workshop.
unknown topicSuccessful response with an empty workshops array.
Blank text or more than 80 charactersExplicit validation error.
Missing topic or an array instead of textSchema validation error.

Now change one workshop title, reconnect or restart the server, and confirm that the response changes. That small exercise shows the difference between the assistant’s knowledge and data returned by a connected tool.

Add a WebMCP tool to a webpage

The same catalog function can be exposed to a browser agent. Keep a normal search form, then register a tool when the API is available. The downloadable demo includes both paths and uses no external services.

  1. Serve the demo. Extract the kit and run python -m http.server 8000 from its folder. Open http://localhost:8000/demo.html; do not rely on opening a file URL.
  2. Try the ordinary form first. Search for AI, MCP and a topic that does not exist. This is the behavior the tool must preserve.
  3. Use a supported test browser. Follow Chrome’s current WebMCP origin-trial or local-testing instructions. Check for document.modelContext in the console. Availability varies by browser and configuration.
  4. Register the tool. Use a precise name, description and JSON Schema. Reuse the same search function as the visible form.
  5. Discover and call it. Inspect the result, then compare it with the form. Clean up registration with an abort signal when the page is left.
const catalog = [
  { id: "intro-ai", title: "Introduction to AI", level: "beginner" },
  { id: "build-mcp", title: "Build an MCP server", level: "intermediate" }
];
export function findWorkshops(topic) {
  if (typeof topic !== "string" || !topic.trim() || topic.length > 80) {
    throw new Error("Use a topic between 1 and 80 characters.");
  }
  const query = topic.trim().toLowerCase();
  return { demo: true, workshops: catalog.filter(w =>
    w.title.toLowerCase().includes(query)) };
}
export async function registerWorkshopTool(doc = document) {
  if (!doc.modelContext) return null;
  const lifecycle = new AbortController();
  await doc.modelContext.registerTool({
    name: "find_workshops",
    description: "Search fictional workshops by topic. Never books a place.",
    inputSchema: {
      type: "object",
      properties: { topic: { type: "string", minLength: 1, maxLength: 80 } },
      required: ["topic"],
      additionalProperties: false
    },
    annotations: { readOnlyHint: true },
    execute: async ({ topic }) => findWorkshops(topic)
  }, { signal: lifecycle.signal });
  return lifecycle;
}

In a supporting browser, this console check exercises the registered tool:

const tools = await document.modelContext.getTools();
const tool = tools.find(t => t.name === "find_workshops");
if (tool) {
  console.log(await document.modelContext.executeTool(tool, { topic: "AI" }));
}

The Python protocol tests, browser search form and native WebMCP tool calls were tested for this guide. Browser support still varies: verify the integration in the specific browsers and assistant environments you plan to support. For a real booking or checkout, return an explicit review state, keep the visible page synchronized, and obtain meaningful confirmation before committing the consequential action.

What companies have actually shown

ExampleVerified implementation or evidenceWhat to take from it
ShopifyStorefront tools expose catalog and cart actions. Checkout support can hand control back for buyer confirmation or challenges.Test your actual theme, checkout and payment path; platform support does not prove every customization works.
StripeIts September engineering study reported 42% fewer tokens, 38% fewer tool calls and 39% faster completion.The study used 60 checkout runs across six models with a fictional retailer, split between WebMCP and baseline. It did not establish merchant sales lift.
LovableThe October 13 changelog added browser tools alongside agent integrations, with an option to use WebMCP without an MCP server.Review the generated tools and their scope rather than assuming every app action should be exposed.
Cloudflare + Commerce.comA beta edge bridge can expose existing commerce tools.Infrastructure can carry tool definitions; it cannot invent correct business rules for an arbitrary site.
MetaOfficial developer examples demonstrate voice-driven web-app actions for glasses.Examples and rollout documentation are not proof of universal device availability or measured production impact.

A separate Shopify benchmark by Gil Greenberg reported average completion falling from 27.4 to 10.3 seconds and 58% lower cost in controlled checkout tasks. That is about 2.7 times as fast for those tasks. Treat it as motivation to run your own evaluation, not a forecast for your store. The source’s aggregate attempt counts are inconsistent, so we do not repeat a sample-size claim.

A practical five-day pilot

DayWorkEvidence to keep
1 · ChoosePick one frequent task and a clear definition of done.Baseline completion, errors and time for representative cases.
2 · SpecifyWrite the tool contract and account boundaries.Inputs, outputs, permission checks, error states and an owner.
3 · ImplementWrap existing business logic with one read-only tool.A working tool plus a human fallback.
4 · Break itTest invalid input, no results, timeouts, expired sessions and access to another account’s records.Expected versus observed results; unresolved failures.
5 · CompareRepeat the same tasks with the same model and starting conditions.Verified success, latency, cost, retries and handoffs.

Track cost per successful task, not only cost per attempt. Record median and slow-tail completion times, tool errors, human interventions and duplicate actions. Compare like-for-like tasks. A tiny learning pilot can expose obvious problems; it cannot prove a statistically reliable revenue lift.

For changes such as creating bookings, updating a CRM or issuing a refund, add a review step with the actual details. Enforce permissions on the server, defend against repeated requests, record the result ID, and provide recovery. Treat text returned from third-party content as data, not instructions that can override the user’s request. Keep secrets and unnecessary personal information out of results and logs.

Proceed when the task is useful, results are verifiable and failures are recoverable. Pause when permissions are unclear, source data is unreliable or there is no owner to maintain the connection. Neither MCP nor WebMCP automatically improves search rankings, creates demand or guarantees agent traffic.

Try it yourself

Download the Python server, protocol tests, browser demo, example host configuration and editable pilot worksheet. No email required.

Download the starter kit (.zip)Open the browser demo

The catalog is fictional. The kit demonstrates the connection mechanics; it is not a deployed booking integration.

Common questions

Do I need to create an MCP server to use an existing one?

No. Connect the provider’s server using its documented setup and a compatible assistant. Build your own only when you need a capability the existing tools do not provide.

Does WebMCP replace a normal website or API?

No. Keep the human interface and the backend’s business rules. WebMCP exposes selected page actions to compatible browser agents.

Will this automatically improve traffic or revenue?

No. Structured actions can make a supported task easier to perform. Discovery, customer demand and commercial results need their own evidence.

Continue with the guide for your role

Sources and further reading

  1. MCP architecture
  2. Python SDK v1 maintenance documentation
  3. Python SDK v2 and migration
  4. Connect an MCP server in VS Code
  5. Chrome WebMCP overview
  6. Current imperative WebMCP API
  7. WebMCP draft specification
  8. Shopify storefront tools
  9. Shopify checkout support
  10. Shopify benchmark by Gil Greenberg
  11. Stripe checkout engineering study
  12. Lovable product changelog
  13. Cloudflare and Commerce.com
  14. Meta WebMCP examples

Original guide and teaching examples by Ashley Kays. Inspired by the questions raised in Department of Product’s WebMCP coverage; independently written and checked against the primary sources above. Sources reviewed November 15, 2026. Cover: AI-generated conceptual illustration. Diagrams: original explanatory graphics. Demo workshops are fictional.