To build a good MCP server you need to think about how the LLM will interact with your tools.
An MCP Server is not simply an API wrapper, though it can be.
However, if its an API wrapper its often lackluster in capability unless the API is comprehensive with features.
In an MCP Server, the tool descriptions, filter options, expected input values, etc all matter greatly. Natural language interactions is what matter here. The tool description of what it does and input values etc is critical.
Tools such as "find_projects" instead of a restful "list projects" is far more useful to an LLM.
Why? Users are asking questions, often about sets or subsets of data. Sometimes thats one record, sometimes thats multiple records. The LLM wants to find/search for things not paginate through pages and pages of data.
Plus pagination is slow and returns tons of data. Pagination is a token monster, it will eat up your context window, so you have to be careful.
Examples:
- User Initiated: "How many projects started in 2025, and already have already been completed"?
- Agent Initiated: "I need to find all projects that reference work item 3351 that were completed in 2025" (e.g. - via Cursor, Claude Code, etc).
If your MCP tool has a filter for `created at` with relational comparison operators (>, =, <, etc) and another filter for status, you can get this data easily with minimal context window impact (if your result is small).
Then with an additional tool to return a single record, `get_project` (that returns the full dataset of the project) you can provide the LLM with tools so it can find and read the data it needs without exhausting its context window.
Example: The LLM returns many projects that were completed. One catches the eye of the user. So they ask "For project `Make it Rain` can you give me the details about it?"
The LLM would then go get the project with the `get_project` MCP tool (or resource - though beware, not all MCP clients fully support resources yet) and show you the data.
While all of this is possible with an API that has a good domain model surface area, its not always possible as many API's are simply REST CRUD operations. Nothing wrong with that, but it makes it more challenging at times.
The moral of the story here is that you have to think about modeling your interactions with MCP tools as if you were telling someone "Hey, here's what I can do for you, and here's how you can ask me about it, and then here's the kind of data you'll get back". Then the LLM can decide "oh I want to use tool x this time, and for details I'll use tool y".
In find/search operations, don't return too much data, just as much as needed for the main use cases of your app. Then provide a tool that the LLM can use go get more data for that particular record, if and when it needs it. This will will keep the MCP tool snappy, keep the context window consumption to a minimum and allow the LLM to get the data it needs when it needs it.
An MCP Server is not simply an API wrapper, though it can be.
However, if its an API wrapper its often lackluster in capability unless the API is comprehensive with features.
In an MCP Server, the tool descriptions, filter options, expected input values, etc all matter greatly. Natural language interactions is what matter here. The tool description of what it does and input values etc is critical.
Tools such as "find_projects" instead of a restful "list projects" is far more useful to an LLM.
Why? Users are asking questions, often about sets or subsets of data. Sometimes thats one record, sometimes thats multiple records. The LLM wants to find/search for things not paginate through pages and pages of data.
Plus pagination is slow and returns tons of data. Pagination is a token monster, it will eat up your context window, so you have to be careful.
Examples:
- User Initiated: "How many projects started in 2025, and already have already been completed"?
- Agent Initiated: "I need to find all projects that reference work item 3351 that were completed in 2025" (e.g. - via Cursor, Claude Code, etc).
If your MCP tool has a filter for `created at` with relational comparison operators (>, =, <, etc) and another filter for status, you can get this data easily with minimal context window impact (if your result is small).
Then with an additional tool to return a single record, `get_project` (that returns the full dataset of the project) you can provide the LLM with tools so it can find and read the data it needs without exhausting its context window.
Example: The LLM returns many projects that were completed. One catches the eye of the user. So they ask "For project `Make it Rain` can you give me the details about it?"
The LLM would then go get the project with the `get_project` MCP tool (or resource - though beware, not all MCP clients fully support resources yet) and show you the data.
While all of this is possible with an API that has a good domain model surface area, its not always possible as many API's are simply REST CRUD operations. Nothing wrong with that, but it makes it more challenging at times.
The moral of the story here is that you have to think about modeling your interactions with MCP tools as if you were telling someone "Hey, here's what I can do for you, and here's how you can ask me about it, and then here's the kind of data you'll get back". Then the LLM can decide "oh I want to use tool x this time, and for details I'll use tool y".
In find/search operations, don't return too much data, just as much as needed for the main use cases of your app. Then provide a tool that the LLM can use go get more data for that particular record, if and when it needs it. This will will keep the MCP tool snappy, keep the context window consumption to a minimum and allow the LLM to get the data it needs when it needs it.
• • •
Missing some Tweet in this thread? You can try to
force a refresh
