8 posts tagged with "technical"

When you're building MCP tools, there's a moment where you realize something counterintuitive: the description field isn't just documentation—it's instruction. Every parameter description you write is a teaching moment where the AI learns not just what a parameter is, but when to use it, why it matters, and how it impacts the operation.

This shift in thinking—from documenting to teaching—changes how you design tools. Let me show you what that looks like in practice.

Here's a problem I kept running into: when you're building an MCP server, you face this weird tension between giving AI agents enough control and not drowning them in options. Build 20 different tools and you're burning context window on redundant functionality. Build 3 tools with no parameters and the AI can't do anything useful.

After shipping dozens of MCP integrations, I found something that actually works: six core tools that balance OpenAI's single-string requirements with rich, parameter-driven operations. It's not arbitrary—there's a reason this number keeps working.

When OpenAI integrated support for Anthropic's Model Context Protocol (MCP) into ChatGPT's deep research feature, they documented something elegant: a two-tool pattern that gives AI agents a consistent way to engage with any data source. If your MCP server implements search and fetch with their specific signatures, ChatGPT knows exactly how to explore your data without custom integration code.

Both tools accept only a single string parameter. That constraint isn't a limitation—it's what makes the pattern universal.

Design Philosophy​

We designed the Weaviate MCP tools following a modern, AI-first approach that prioritizes:

1. Rich, Actionable Descriptions - Every tool and parameter has extensive descriptions that tell AI agents not just what something is, but when to use it, why it matters, and how it impacts the operation
2. OpenAI MCP Connector Compatibility - search and fetch tools follow OpenAI's ChatGPT Connectors and Deep Research specification
3. Smart ID Routing - Universal fetch tool uses colon-separated IDs (weaviate:object:uuid, weaviate:schema:CollectionName) to encode multiple resource types in a single endpoint
4. Consolidated CRUD Operations - Single weaviate_upsert tool handles insert/update and single/batch operations intelligently
5. Granular List Tools - Object-specific parameters for fine-grained control over discovery and browsing
6. Maximum Tool Count = 10 - Design constraint to ensure focus and avoid overwhelming AI agents with too many options

Marketing teams face a familiar challenge: exciting AI tools exist, but connecting them to existing systems feels like solving a puzzle with missing pieces. Enter Model Context Protocol (MCP) — an open standard that acts like a universal adapter, letting AI talk directly to your CRM, email platform, analytics tools, and more.

Think of MCP as the missing link between AI's potential and your marketing reality. Instead of building custom integrations or switching between disconnected tools, you can create workflows where AI actually understands your business context.

Following our prior post on wiring up an MCP server for our Django app — see How We Integrated Model Context Protocol (MCP) into Our Django App — we went back and revisited the architecture. "Too many tools" is still a huge problem for LLM productivity, which has continued into GPT5 and the latest Claude models so probably won't be solved toon. Cursor and Claude both work better when they have fewer tools to choose from, and our original setup exposed too many single-purpose GET tools. So we consolidated everything into a single, strongly-typed batch tool.

The result: one get tool, clearer schema, faster concurrent fetches, and less model confusion.

Most “MCP integrations” ship as thin wrappers over existing REST endpoints because it’s the fastest way to get something working, but that convenience often fights how agents actually reason and act. If you want MCP that agents can use reliably, design it like an action‑oriented RPC interface rather than a collection of CRUD‑style endpoints.

MCPs work like magic. Internally we use them relentlessly inside Cursor, for Linear issues in particular. We decided to ship an MCP server with MCP Bundles mainly because it made sense for us to have it on our own product for testing, before we even provided it to our customers. We built it quickly and made choices-of-least-resistance so there may be better ways to do everything. This is why we wanted to share our experience, would love to hear your feedback.

So the headline is we decided to implement an MCP server, Model Context Protocol (MCP), in our Django application, built on top of our existing API endpoints, and get it working with Cursor and Claude 3.7.