We Built 126 MCP Tools. But It Is Not the Best Solution for Agent

This is a 10-part series sharing how Apidog developed Apidog CLI, a command-line tool for API testing and API lifecycle management. Read in order or jump to any post that interests you:

When MCP became the industry hotspot, we built a complete MCP Server with 126 generated tools. Here's what went wrong—and why more tools doesn't mean better Agent enablement.

The MCP Hype

In early 2025, MCP (Model Context Protocol) became an industry hotspot.

Anthropic promoted the protocol. Cursor, Claude Code, Antigravity, various Agent IDEs, and numerous SaaS products quickly followed suit. The protocol promised a standardized way for AI Agents to connect to external tools and data sources.

During that period, almost every product with an API was asked the same question:

"Do you have MCP?"

For Apidog, this choice seemed especially natural.

Why MCP Seemed Like the Answer

Apidog itself had accumulated a comprehensive set of API development capabilities:

• API documentation
• Schema definitions
• Mock servers
• Test cases
• Test scenarios
• Test suites
• Test reports
• Import/export workflows
• Branch collaboration
• And many more

If Agents were to become the new software entry point—a new way users interact with products—then exposing these capabilities through MCP seemed like a necessary ticket to punch.

We believed that if we could package our capabilities as MCP tools, Agents would be able to:

• Query API documentation
• Create test cases
• Run test scenarios
• Import/export project data
• Manage environments and variables
• Collaborate across branches

The logic was straightforward: more capabilities exposed = more Agent enablement.

What We Actually Built

We didn't take this lightly.

Apidog MCP was not a simple demo with a handful of hand-written endpoints. It was a complete MCP Server:

Session System

The MCP client first initializes a session. The server generates a sessionId and saves session state through Redis. Subsequent requests continue to access with the sessionId.

In other words, it wasn't a one-time HTTP call, but a protocol-level session system.

Tool Categories

The tool layer was also not hand-written with a few fixed endpoints. We divided Apidog's tools into several categories:

That last category: 126 generated tools.

Each generated tool had:

• A unique identifier
• A specific API path
• An HTTP method (GET, POST, PUT, DELETE, etc.)
• A complete input Schema with field descriptions, types, and enum values
• A defined return structure

Progressive Disclosure

To reduce tool exposure pressure, we also built a dynamic discovery layer:

The Agent could:

1. First search for available endpoint tools (listOpenApiEndpoints)
2. Then get the OpenAPI details of a specific tool (getOpenApiDetails)
3. Finally execute the actual HTTP call by tool id (executeOpenApi)

This was our attempt at progressive disclosure. We didn't simply expose all underlying endpoints directly and explicitly. We hoped that Agents would search first, then get details, and finally execute.

The Wall of Random Tools

But when entering real tasks, problems quickly emerged.

Consider a simple user request:

"Help me add a test for this endpoint and run verification."

From an implementation perspective, this is a reasonable request. Apidog has the capabilities to:

• Find endpoints
• Create test cases
• Run test scenarios
• Generate reports

But from the Agent's perspective, this simple request actually triggers a series of continuous judgments:

The Agent doesn't just need to find the right tool. It needs to solve the "which tool to use" problem first, before it can even start solving the user's problem.

From an implementation perspective, these problems can all be solved through tools. From the Agent experience perspective, they form a wall of random tools.

The Four Structural Problems

Through real-world testing and internal feedback, we identified four structural problems with the MCP approach.

Problem 1: Tool Discovery Costs Rise Quickly

Apidog is not a product that can be described with just a dozen endpoints.

When tools grow from a dozen to dozens or hundreds, the Agent needs to solve the "which tool to use" problem before it can start solving user problems.

We tried writing workflows into tool description (the field used to expose tools to AI Agents). For example, a tool description would explicitly state:

"Before querying endpoint data, you need to confirm the project through another tool first, then get project metadata through a third tool, and finally call the current tool."

This method works in small-scale tool sets. But in a massive tool wall, description itself competes for model attention.

The more guidance we wrote into descriptions, the more tokens consumed—and the less likely the Agent would actually read and follow them.

Problem 2: Business Schema Invades Context

Each MCP tool is not just a tool name.

Behind every tool are:

• description (what the tool does)
• input schema (parameters, types, required/optional)
• Field explanations (nested structures, constraints)
• Enum values (allowed options)
• Return structures (response format, error handling)

Let's do a conservative estimate:

A user's question might be only 50 characters. But the model is forced to first introduce 50,000 tokens of tool descriptions—just for one MCP server.

This isn't theoretical. Industry data supports it.

Cursor's official blog post "Dynamic Context Discovery" provided valuable reference data: by converting MCP tool descriptions, terminal sessions, and long conversations into on-demand loadable context, runtime token consumption was reduced by 46.9%.

Trae's approach was more direct: limiting MCP tool count and single tool description length:

• Tool count upper limit: 40
• Single tool description limit: 8000 characters

In fact, during early internal testing, many teams reported that Apidog MCP had issues with some tools not being able to be invoked in Trae. The Agent was forced to make trade-offs due to limited model context, and external tools were the first to be "cut."

These solutions all point to the same fact:

Tool descriptions cannot infinitely enter model context.

Problem 3: Protocol Sessions Make Execution Chains Heavier

Apidog MCP server needs to handle:

For a simple tool call, these costs are acceptable. For Agent tasks with large numbers of calls and frequent exploration, these state management requirements increase complexity on both server and client sides.

When implementing Apidog MCP, the team consumed significant energy troubleshooting and adapting to different Agent clients (Cursor, Claude Code, Antigravity, Trae, etc.). However, protocol compatibility issues persisted, and the official MCP protocol continued to be patched with new versions.

All parties suffered greatly.

Problem 4: Atomic Tools Cannot Naturally Express Product Semantics

In Apidog's test scenarios, it's not just a simple steps array expression.

A test scenario involves:

After splitting these into multiple MCP tools, the Agent still has to undertake the test orchestration work itself.

The more atomic the tools, the more the model needs to understand product internal semantics:

• Why does import need read-back?
• Why do internal cases have different update markers?
• Why do assertions require specific comparators?
• Why does variable extraction have type constraints?

This is obviously beyond the model's capability range.

It forced the Apidog team to proactively make technical engineering adjustments for internal product semantics. Atomic endpoints passively added a conversion layer, just to adapt to a single MCP tool layer dispatch.

The engineering challenges and post-maintenance costs are undoubtedly arduous.

The Root Cause

The root cause of these four problems is the same thing:

MCP is better at connecting tools, but complex R&D tasks need more than tool connection—they need executable engineering processes.

For simple products with a dozen well-defined operations, MCP works well. The Agent can reasonably guess the right tool, call it, and get a result.

For products like Apidog—with dozens of modules, hundreds of operations, nested structures, hidden workflows, and product-specific semantics—MCP alone creates a wall of random tools that Agents struggle to navigate.

What We Learned

The Pivot

This realization led us to ask a different question:

If MCP isn't the answer for agent enablement, what is?

We didn't abandon MCP's value—it provides standardized connections, which is important for the ecosystem. But we needed something that could:

• Express workflows, not just tools
• Guide Agents through sequences
• Validate before writing
• Enforce engineering quality gates
• Absorb complexity into the system

The answer we arrived at: CLI + SKILL.

In the next post, Why We Developed a Brand-new Apidog CLI , we'll explore the architectural shift—where complexity moved from model context to the engineering system, and why that changes everything for Agent enablement.

Key Takeaways

• MCP became the industry answer to "how do Agents connect to tools"
• We built 126 MCP tools, thinking more tools = better enablement
• Real tasks revealed four structural problems: discovery costs, context invasion, session overhead, product semantics
• The root cause: MCP connects tools, but complex tasks need executable processes
• More tools is a cost, not a benefit, when tool descriptions consume context

Download Apidog to design, mock, test, and document APIs in one workspace. Learn more about Apidog CLI for command-line API testing, CI automation, and AI Agent workflows.