MCP Tutorial - Expose Python services as AI tools

MCP (Model Context Protocol) lets AI clients like Claude Code, Cursor and ChatGPT discover and call your Python services as tools, without any glue code. You expose services once through an MCP gateway and every compatible client can use them, protected by the same security definitions and audit trail as your REST APIs.

Connect Claude Code to Zato

Four steps: install Zato, create an API key, create an MCP gateway, register it with Claude Code.

Install Zato

If you do not have Zato running yet, install it via Docker - it takes under 5 minutes.

Create an API key

MCP gateways always require authentication - only authorized clients can access your tools. Both API keys and Basic Auth are supported, this tutorial uses an API key.

1. Open the web admin dashboard at http://localhost:8183
2. Go to Security > API keys and click Create an API key
3. Enter mcp-tutorial as the name and abc123 as the API key
4. Click OK

Create an MCP gateway

A gateway is the endpoint MCP clients connect to - it decides which services are exposed as tools and who may call them. You can create one in the Dashboard or keep it as YAML in git:

Dashboard

1. Go to AI > MCP gateways and click Create a new MCP gateway
2. Enter tutorial as the name
3. Enter /mcp/tutorial as the URL path (the field is pre-filled with /mcp/, type the rest)
4. In the Services picker, drag demo.echo to the Assigned zone
5. In the Security picker, drag mcp-tutorial to the Assigned zone
6. Click OK

GitOps

The same gateway as enmasse YAML, versioned in git and imported per environment:

mcp_gateway:

  - name: tutorial
    url_path: /mcp/tutorial
    services:
      - demo.echo
    security_groups:
      - mcp-tutorial

To import it, click System > Config > Import enmasse - the GitOps page covers the full schema and how secrets stay in environment variables.

Your gateway is now live at http://localhost:11223/mcp/tutorial.

Register the gateway with Claude Code

Tell Claude Code where your MCP gateway is. You can do this globally (available in every project) or per project:

claude mcp add --transport http --header "X-API-Key: abc123" zato http://localhost:11223/mcp/tutorial

{
  "mcpServers": {
    "zato": {
      "type": "http",
      "url": "http://localhost:11223/mcp/tutorial",
      "headers": {
        "X-API-Key": "abc123"
      }
    }
  }
}

Call your first tool

Start Claude Code. It connects automatically - establishing a session, discovering all assigned tools, and making them available for every conversation.

Ask Claude Code: "What tools do you have access to from Zato?"

Now ask: "Use the demo.echo tool to echo the message 'Hello from MCP'"

That is it. Claude Code is calling your Zato service as an MCP tool - and a client that sends several calls in one JSON-RPC batch gets them all handled too.

Write your own service

Now that Claude Code is connected, give it something more interesting to work with.

Deploy the service

Open the Zato IDE at http://localhost:8183, create a new service, paste this code, and click Deploy:

from zato.server.service import Service

# ##############################################################################

class CustomerBalance(Service):
    """ Returns the account balance and recent transactions for a given customer.
    """
    name = 'api.customer-balance'

    input = 'customer_id'
    output = 'customer_id', 'balance', 'currency', 'transactions'

    def handle(self):

        # Read the customer ID from the request ..
        customer_id = self.request.input.customer_id

        # .. and return a response.
        self.response.payload = {
            'customer_id': customer_id,
            'balance': '1,528.40',
            'currency': 'USD',
            'transactions': [
                {'id': 'TX-001', 'amount': 450.00},
                {'id': 'TX-002', 'amount': 728.40},
                {'id': 'TX-003', 'amount': 350.00},
            ],
        }

# ##############################################################################

Add it to the gateway

1. Go to AI > MCP gateways and click Edit on the tutorial gateway
2. In the Services picker, drag api.customer-balance to the Assigned zone
3. Click OK

Ask Claude Code

Back in Claude Code, ask: "What is the balance for customer CUS-001?"

Claude Code discovers your new tool automatically and calls it:

How security works

Every MCP gateway requires authentication - there are no open gateways. You already set this up: the mcp-tutorial API key is assigned to the gateway and every client sends it in the X-API-Key header.

Basic Auth works too - clients send a standard Authorization header instead. So do bearer tokens, including JWTs from identity providers such as Keycloak or Microsoft Entra ID, which Zato verifies locally against the provider's keys.

To give access to another client:

1. Go to Security > API keys or Security > Basic Auth and create a new definition
2. Go to AI > MCP gateways and click Edit on the tutorial gateway
3. In the Security picker, drag the new definition to the Assigned zone
4. Click OK

A gateway can have multiple definitions assigned at the same time - each client gets its own credentials and any of them can be revoked independently. Without valid credentials, requests are rejected.

Agent filters

A tool's full response is not always what an agent needs - with agent filters, the agent asks for exactly the part it wants and the server does the work.

1. Go to AI > MCP gateways and click Edit on the tutorial gateway
2. Check Allow agent filters
3. Click OK

Every tool now accepts an optional response_filter parameter - a JSONata expression, JSONata being a query language for JSON, that runs on the server before the response is returned.

Ask Claude Code: "What is the total of all transactions for CUS-001? Use a response filter so you only receive the total."

The agent passes $sum(transactions.amount) in response_filter and receives a single number - the server does the arithmetic and the model spends no tokens on a list it would only add up itself.

The agent filters page covers the expressions with more worked examples.

What you built

• An MCP gateway that exposes Python services as tools for AI clients
• Claude Code connected to your services and using them in conversations
• A custom service that LLM clients discover and invoke automatically
• API key security so only authorized clients can access your tools
• Agent filters that let agents shape tool responses on the server

From here, the MCP gateway reference covers everything this tutorial did not - and the gateway's governance controls, from the audit log that records what each agent did to the response controls that remove PII and cap response sizes, each have a page of their own.

Learn more