Getting Started with MCP Server - Agent

Create the project

Run:

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

Ask the agent to expose one tool

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

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

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:

Code
curl -i http://localhost:9000/todos

Expect 200 OK and a JSON response containing todos.

Test the MCP tool

Start MCP Inspector in another terminal:

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

Connect your coding agent

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

Code
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 and provide its hosted /mcp URL.