MCP Server Architecture Best Practices

MCP Servers as Units of Entitlement

In the Mindset AI platform, you can't entitle an agent to individual tools. You entitle an agent (or agent session) to an MCP server, and that agent then has access to all tools on that server.

This is analogous to how knowledge contexts work: you entitle an agent to a context, not to individual pieces of content within that context.

This architectural constraint should drive how you organize your MCP servers.

Organize by Entitlement, Not by API

The primary recommendation is to split your MCP servers based on who should have access to the tools.

The question to ask for every tool you build: Which users should be able to use this?

Group tools together when they share the same answer.

Example: admin vs. regular user tools

Do this instead:

Regular users never see admin tools. Admins get both MCP servers entitled to their sessions.

Why Visibility Matters — Not Just Authorization

You might think: "Our tools already check permissions using the x-user-id header. Why does visibility matter?"

Two reasons.

User experience

Users don't directly see a list of available tools, but they can ask the agent — and the agent will tell them. If the agent has access to a delete_user tool, it will mention this capability when asked "What can you do?"

The user might then ask the agent to delete someone. The agent will attempt it, fail, and return a permission error. That's a poor experience. Users shouldn't be told about capabilities they can't actually use.

LLMs can't keep secrets

You can't rely on system prompts or instructions to hide tools from users.

Defense in Depth: The Complete Authorization Model

Best practice is a layered approach.

Tool Naming: Maintain Semantic Distance

When an agent has access to multiple MCP servers, all tools from all servers appear in the agent's tool inventory. This creates a potential problem: tool name collisions and semantic confusion.

The problem

If two MCP servers both have a tool called add_user — one in an HR System MCP (described as "Add user to HR system") and another in a Training System MCP (described as "Add user to course") — the LLM uses both the tool name and description to select the right tool. With two identically-named tools, this breaks down.

Users occasionally give explicit instructions like "use the add user tool to enrol them in the course." With two identically-named tools, the LLM can't reliably determine which one the user means. This leads to incorrect tool selection, unpredictable behaviour, and user frustration.

The solution

Give tools names that are descriptive and unambiguous.

Naming guidelines:

• Be specific: get_user_enrolled_courses not get_courses
• Include the domain: create_employee_record not create_record
• Describe the action clearly: enroll_user_in_course not add_user
• Avoid generic verbs alone: search_training_catalog not search

When planning multiple MCP servers, coordinate tool naming across teams to prevent collisions.

Tool descriptions matter just as much

The tool description is what the LLM primarily uses to decide when to call your tool. A poor description leads to tools being called at the wrong time — or not at all.

Write descriptions that explain what the tool does, when it should be used, and who it's for.

"Add user"

"Enroll a user in a training course. Use when a manager
needs to assign required training to an employee."

Help the LLM get it right

Beyond the basic description, include parameter guidance directly in the tool description — especially for tools with multiple parameters:

• Date formats: specify expected formats (e.g. "date must be YYYY-MM-DD")
• Categorical values: if a parameter accepts a small set of values, list them (e.g. "status must be one of: pending, approved, rejected")

This upfront guidance reduces failed calls and retries.

Write error messages that guide, not just fail

When a tool is called with invalid parameters, the error message should help the LLM succeed on the next attempt.

"Invalid"

"Invalid status value. Status should be one of 'pending', 'in progress', 'done', 'failed'"

A helpful error message enables the agent to self-correct rather than fail repeatedly or give up.

Per-API vs. Per-Use-Case Organization

Neither pure per-API nor pure per-use-case is the right answer. Organize by entitlement boundaries.

If your Learning API has both student tools and instructor tools, split them:

• Student Learning MCP: get_my_courses, submit_assignment, view_my_grades
• Instructor Learning MCP: grade_assignment, view_class_roster, create_announcement

If a use case like "Preceptor Selection" requires tools that only preceptor coordinators should access, create a dedicated MCP server for that role — even if the underlying tools call multiple backend APIs.

Decision Framework

Use this process when designing your MCP server architecture.

1. List all tools

   Document every tool you need to build.

2. Identify user roles

   Who are the distinct user types? (e.g. students, instructors, admins, coordinators)

3. Map tools to roles

   For each tool, which roles should have access?

4. Group by entitlement

   Tools that share the same role entitlement go in the same MCP server.

5. Check for naming conflicts

   Make sure tools across all MCP servers have semantically distinct names.

6. Implement tool-level authorization

   Regardless of MCP server organization, implement authorization checks in every tool.

Summary