Tool Definition API
How to define and register MCP tools using the mcp Python SDK.
Tool Schema
Each tool is defined as a Tool object with a JSON Schema for its input:
from mcp.types import Tool
Tool(
name="ubuntu_read_file",
description="Read a file from the Ubuntu server filesystem.",
inputSchema={
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Absolute path to the file on the host.",
},
},
"required": ["path"],
},
)
Registration
Tools are registered in the server's setup() method using decorators:
def setup(self):
@self.server.list_tools()
async def list_tools() -> list[Tool]:
return [
Tool(name="tool_one", ...),
Tool(name="tool_two", ...),
]
@self.server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
return await self.handle_tool_call(name, arguments, self._dispatch)
Dispatch Pattern
Use match/case for clean routing:
async def _dispatch(self, name: str, arguments: dict) -> dict:
match name:
case "ubuntu_read_file":
return await read_file.read_file(arguments, self.enforcer, ...)
case "ubuntu_write_file":
return await write_file.write_file(arguments, self.enforcer, ...)
case _:
raise ValueError(f"Unknown tool: {name}")
Input Schema Best Practices
- Always include
"type": "object"at the top level - Mark required parameters in the
"required"array - Provide descriptions for every parameter
- Use
"enum"for parameters with a fixed set of values - Use
"default"for parameters with sensible defaults
Permission Integration
Always call the enforcer in your tool handler:
async def read_file(arguments, enforcer, mount_prefix, tool_name):
path = arguments["path"]
# Permission check (will raise ForbiddenError if denied)
enforcer.check("read", path, tool_name)
# Path resolution (block traversal attempts)
resolved = enforcer.safe_resolve_path(path, mount_prefix, allowed_bases)
# Do the work
content = resolved.read_text()
return {"path": path, "content": content}
The permission check should happen before any work is done. If the check fails, no files are read, no commands are run, no API calls are made.