# Getting Started with MCP Server - Agent

<WizardSteps build="mcp-server" method="agent" />

<MethodTabs build="mcp-server" method="agent" />

Use a coding agent to turn a Todo API into an MCP server. The finished server
exposes one read-only tool, which you'll call from MCP Inspector before using it
with your agent.

## Prerequisites

- [Node.js](https://nodejs.org/en/download) 24 or later.
- An installed coding agent, such as Codex, Claude Code, or Cursor.
- A [Zuplo account](https://portal.zuplo.com).

## Build your MCP server with an agent

<Stepper>

1. **Create the project**

   Run:

   ```bash
   npx create-zuplo-api@latest todo-mcp
   cd todo-mcp
   ```

   When prompted, choose **Yes** to create a matching Portal project, complete
   sign-in, and select your Zuplo account. Select the coding agent you use when
   asked. The CLI creates and links the hosted project. See
   [`create-zuplo-api`](../../cli/create-zuplo-api.mdx).

   :::tip{title="Zuplo skills"}

   The scaffold installs Zuplo skills in this project for Codex and Cursor and
   configures the Claude Code plugin. If setup fails, follow
   [Agent Skills](../../build-with-ai.mdx#agent-skills) from this directory
   before starting your agent.

   :::

2. **Ask the agent to expose one tool**

   Open your agent in the project directory and use this prompt:

   ```text
   Read the project instructions and bundled Zuplo docs. Turn the default Todo
   API into an MCP server with exactly one read-only tool.

   In config/routes.oas.json, keep the existing GET /todos URL forward handler
   pointing to https://todo.zuplo.io. Set its operationId to getTodos. Add an
   x-zuplo-route.mcp object with type "tool", name "getTodos", and annotations
   { "readOnlyHint": true }.

   Add a POST-only /mcp operation with operationId todo-mcp-server, a 200
   response description, and x-zuplo-route with corsPolicy "none" and handler:
   {
     "module": "$import(@zuplo/runtime)",
     "export": "mcpServerHandler",
     "options": {
       "name": "Todo MCP server",
       "version": "1.0.0",
       "operations": [{ "file": "./config/routes.oas.json", "id": "getTodos" }]
     }
   }

   Do not expose create, update, or delete operations as MCP tools. Keep the
   sample unauthenticated for this local exercise; don't claim it is ready
   for private data. Preserve unrelated files and routes.

   Run npm run dev and confirm GET /todos returns 200. Use an MCP client to
   check that tools/list exposes exactly getTodos and tools/call returns todos.
   If you cannot run an MCP client, say which checks remain for me. Do not
   deploy. Show the diff and explain how to test with MCP Inspector.
   ```

   For the underlying configuration, see the
   [MCP Server handler](../../handlers/mcp-server.mdx).

3. **Review the route and start the server**

   Check the diff before running the agent's code. The `/mcp` handler's
   `operations` list should contain only `getTodos`, and that ID must match
   `GET /todos`.

   Start `npm run dev` if the agent hasn't left it running. In another terminal,
   run:

   ```bash
   curl -i http://localhost:9000/todos
   ```

   Expect `200 OK` and a JSON response containing todos.

4. **Test the MCP tool**

   Start MCP Inspector in another terminal:

   ```bash
   npx @modelcontextprotocol/inspector
   ```

   Open the URL printed by Inspector. Select **Streamable HTTP**, enter
   `http://localhost:9000/mcp`, and connect. List tools: there should be exactly
   one, `getTodos`. Run it with an empty arguments object `{}`. The result
   should contain the Todo API response without a tool error.

   A missing tool usually means the `operationId` and handler's `id` don't
   match. If the tool errors, test `/todos` directly to distinguish an upstream
   problem from an MCP configuration problem.

5. **Connect your coding agent**

   For Codex, register the HTTP MCP server from your terminal:

   ```bash
   codex mcp add todo-api --url http://localhost:9000/mcp
   ```

   Start a new Codex session so it loads the server. For another client, use its
   HTTP MCP configuration with the same URL. Keep the gateway running, then ask
   the agent to `Use getTodos to list the todos`. Approve the tool call and
   check that the response matches the Inspector result.

   Cloud-hosted clients can't reach your computer's `localhost`. To use one,
   [deploy the project](../gateway/deploy-to-the-edge/local.mdx) and provide its
   hosted `/mcp` URL.

</Stepper>

This local sample has no authentication. Before exposing private operations,
configure
[MCP server authentication](../../articles/configuring-auth0-for-mcp-auth.mdx).

## Next steps

- [Choose tools in the Route Designer](./local.mdx) to add more operations.
- [Configure the MCP Server handler](../../handlers/mcp-server.mdx) for your
  API's tools.
- [Add authentication](../../articles/configuring-auth0-for-mcp-auth.mdx) before
  sharing a server that accesses private data.