MCP Tool Inventory: Profile Server Tools with Python
Yes, you can profile a Model Context Protocol (MCP) server’s advertised tools with Python. By connecting to the server through the MCP Python SDK, you can list all tool definitions and inspect their names, descriptions, and input schemas, then build a profile of what the server offers.
What Is an MCP Server Tool?
An MCP (Model Context Protocol) server exposes capabilities to AI assistants through a standardized JSON-RPC interface. Tools are one of the primary capabilities: they are functions the server can execute on request. Each tool has a unique name, a human-readable description, and a JSON Schema that defines its input parameters. When a client (like Claude Desktop or a custom Python app) connects, it can call tools/list to retrieve all available tools.
Profiling these tools means extracting that list and organizing it into a readable format—often a table or dictionary—so you can see at a glance what the server can do, what parameters each tool expects, and whether any tools are missing descriptions or schemas.
Prerequisites for Profiling
Before you write any code, you need a few things in place:
- Python 3.9+ – The MCP SDK requires a recent Python version.
- MCP SDK installed – Run
pip install mcpto get the official SDK. - A running MCP server – This could be a local script (stdio transport) or a remote server (HTTP/SSE).
- Access to the server’s configuration – You need to know the command line to start it, or the URL if it’s remote.
If you’re profiling a server you didn’t write, check its documentation for the exact startup command. Many servers are distributed as Python packages or Node.js modules.
How to List Tools with the Python SDK
The core operation is straightforward. You create a client session, connect to the server, and call list_tools(). Here’s a minimal example for a stdio-based server:
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
server_params = StdioServerParameters(
command="python",
args=["my_server.py"]
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
tools = await session.list_tools()
for tool in tools.tools:
print(f"{tool.name}: {tool.description}")
print(f" Schema: {tool.inputSchema}")
print()
asyncio.run(main())
For an HTTP server, you’d replace the stdio client with the HTTP client and provide the URL instead of a command. The list_tools() method returns a ListToolsResult object, which contains a list of Tool objects. Each Tool has name, description, and inputSchema attributes.
Building a Profile from the Tool List
Once you have the raw list, you can turn it into a structured profile. A good profile answers questions like:
- How many tools does the server expose?
- Are all descriptions non-empty?
- What are the most common parameter types?
- Which tools have optional vs. required parameters?
- Are there any tools with no input schema?
Here’s an example that builds a simple profile dictionary:
def profile_tools(tools):
profile = {
"total": len(tools),
"missing_description": [],
"missing_schema": [],
"parameter_types": {},
"tools": []
}
for tool in tools:
entry = {
"name": tool.name,
"description": tool.description,
"parameters": list(tool.inputSchema.get("properties", {}).keys())
}
profile["tools"].append(entry)
if not tool.description:
profile["missing_description"].append(tool.name)
if not tool.inputSchema:
profile["missing_schema"].append(tool.name)
props = tool.inputSchema.get("properties", {})
for prop in props.values():
ptype = prop.get("type", "unknown")
profile["parameter_types"][ptype] = profile["parameter_types"].get(ptype, 0) + 1
return profile
You can then print this profile as JSON or save it to a file for documentation.
Common Pitfalls and How to Avoid Them
Profiling sounds simple, but there are a few traps:
- Server not starting – If the command or arguments are wrong, the client will hang or crash. Always test the server manually first.
- Schema format variations – Some servers use JSON Schema draft-07, others use OpenAPI 3.0. The
inputSchemafield may have different structures. Handle bothpropertiesandparameterskeys. - Descriptions that are None – Not all servers provide a description. Check for
Nonebefore callinglen(). - Nested schemas – A parameter might be an object with its own properties. Your profile should recursively walk the schema if you need full detail.
- Async context – Forgetting to use
async withwill cause resource leaks. Always close the session properly.
Comparing Multiple Servers
If you’re evaluating several MCP servers, you can profile each and compare them side by side. For example, you might have a local file server and a remote database server. Write a script that takes a list of server configurations, profiles each, and outputs a combined report.
When comparing, pay attention to:
- Tool naming conventions – Are names consistent and descriptive?
- Schema quality – Are required fields actually required? Are types specified?
- Description clarity – Could an AI model understand when to use each tool?
This kind of comparison is useful when choosing between servers or when auditing your own server for gaps.
Frequently Asked Questions
Can I profile a remote MCP server without local code?
Yes, if the server exposes an HTTP endpoint. Use the mcp.client.http module instead of stdio. You’ll need the server’s URL and any authentication headers. The rest of the profiling logic stays the same.
What if the server doesn’t support the MCP SDK version I have?
The MCP protocol is versioned. If you get a handshake error, check the server’s supported protocol version and pin your SDK to match. Most servers support a range, but older ones may require an older SDK.
How do I handle tools with no input schema?
Some tools take no parameters. The inputSchema might be an empty object or missing entirely. In your profile, treat these as having zero parameters. They’re still valid tools; they just don’t need input.
Can I automatically generate documentation from the profile?
Yes. Once you have the profile, you can convert it to Markdown, HTML, or even a JSON schema file. Many teams use this to keep API docs in sync with the actual server.
Is profiling safe for production servers?
Listing tools is a read-only operation—it doesn’t execute any tool. However, connecting to a production server may trigger logging or authentication. Use a test environment if possible, and never profile a server you don’t have permission to access.
What’s the difference between list_tools() and tools/call?
list_tools() returns metadata about available tools. tools/call actually executes a tool with given arguments. Profiling only uses the former, so it’s safe and non-destructive.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.