# MCP tool schemas

Expose each assigned service as one MCP tool with a schema derived from its input and output.

Each service assigned to an [MCP gateway](https://zato.io/docs/ai/mcp/index.html) becomes one tool, and everything an AI agent learns about it through `tools/list` comes from the service itself - there is no separate tool definition to write or keep in sync.

| Tool element | Where it comes from |
| --- | --- |
| `name` | The service's name, e.g. `billing.get-invoice` |
| `description` | The service's docstring - this is what the agent's model reads when deciding which tool to call, so write docstrings for the model as much as for colleagues |
| `inputSchema` | Generated from the service's declared input |
| `outputSchema` | Generated from the service's declared output |

## Input schema generation {#input-schema-generation}

Both I/O styles produce the same JSON Schema. With plain declarations, each element maps to its JSON Schema type - `Int` becomes `integer`, `Bool` becomes `boolean`, `Float` becomes `number`, `Dict` becomes `object`, `List` becomes `array`, `Date`, `DateTime` and `UUID` become strings with their `format`, and text-like elements become strings:

```python
class GetInvoice(Service):
    """ Returns one invoice by its ID, optionally with line items.
    """
    input = 'invoice_id', '-include_items'
```

With dataclass models, each field's Python annotation maps to its JSON Schema type - `str`, `int`, `float`, `bool`, `list[T]` with its element type, `dict`, dates, `Decimal`, `UUID` - and nested dataclasses recurse into nested object schemas. A field is required unless it has a default or its type is optional, and required names are listed in the schema's `required` list. In plain declarations the `-` prefix marks an element optional.

When [argument validation](https://zato.io/docs/ai/mcp/argument-validation.html) is on, it enforces the generated schema itself, so the schema agents see and the schema calls are checked against are always the same one.

A service with no declared input produces a schema that accepts any arguments.

## Exposed services {#exposed-services}

- Only services assigned to the gateway appear - the **Services** picker on the wizard's step 01 lists what can be assigned.
- Internal services - names starting with `zato.` or `pub.zato.` - are never exposed, regardless of the assignment. The picker does not offer them, and the runtime refuses them even if configuration were to name them.
- Tools are listed in a deterministic alphabetical order, so clients can cache the list.

## Live updates {#live-updates}

Hot-deploying a changed service rebuilds the tool list of every gateway that exposes it - the next `tools/list` already advertises the schemas the redeployed code declares, with no restarts. Editing the gateway itself also rebuilds its registry without a restart.

The **Export** document described under [sharing a gateway with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) uses the same schema generation.

## See also {#see-also}

- [Argument validation](https://zato.io/docs/ai/mcp/argument-validation.html) - Checks tools/call arguments against the same generated schema
- [Sharing with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) - Exports the tool list with its schemas as one server.json document
- [MCP gateways](https://zato.io/docs/ai/mcp/index.html) - Configuration, endpoint behavior and the governance controls
- [Tool selection](https://zato.io/docs/ai/examples/tool-selection.html) - Docstrings and schemas that steer agents to the right tool

## Learn more {#learn-more}

- [MCP tutorial](https://zato.io/tutorials/mcp/01.html) - Expose Python services as AI tools and connect Claude Code in minutes
- [AI Integrations overview](https://zato.io/docs/ai/) - Both directions of AI traffic in one platform, and where to start
- [MCP gateway reference](https://zato.io/docs/ai/mcp/) - Configuration, endpoint behavior and the governance controls
- [MCP gateway security](https://zato.io/docs/ai/mcp/security.html) - API keys, Basic Auth and bearer tokens for AI agents
- [MCP response controls](https://zato.io/docs/ai/mcp/response-controls.html) - PII removal, prompt-injection safeguards and token-denominated size caps
- [MCP audit log](https://zato.io/docs/ai/mcp/audit-log.html) - What each agent did, when and with what outcome - payloads never recorded
- [MCP alerts](https://zato.io/docs/ai/mcp/alerts.html) - Failing backends, agents stuck in a loop and gateways with too many tools
- [Cost and limits](https://zato.io/docs/ai/cost-and-limits.html) - Every setting that caps AI cost and traffic, with worked examples
- [GitOps for AI integrations](https://zato.io/docs/ai/enmasse.html) - LLM connections and MCP gateways as YAML in version control
- [AI examples](https://zato.io/docs/ai/examples/) - Complete, runnable scenarios - one real-world need per file