MCP Mastery: Scoping, Catalogs, and Errors

1. Administrative Scoping & Credential Security

Orchestrators must manage tool availability at both personal and project levels while protecting sensitive credentials.

• Project-scoped servers (.mcp.json): use for standardized team tooling shared through version control. Commit the server definition, not secrets.
• User-scoped servers (~/.claude.json): use only for personal, local, or experimental servers that should not be shared with the team.
• Secure credential management: never hardcode secrets. Use environment variable expansion such as ${GITHUB_TOKEN} or ${DB_PASSWORD}.
• Community vs. custom servers: prefer existing community MCP servers for standard integrations like Jira or Slack. Reserve custom servers for proprietary, team-specific logic.

{
  "mcpServers": {
    "crm-db": {
      "command": "node",
      "args": ["./mcp-servers/mock-db-server.js"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

2. Reducing the Discovery Tax with MCP Resources

Agents should plan tool sequences using navigable catalogs rather than burning tokens on exploratory trial-and-error calls.

2a. The Discovery Tax

Without a catalog, an agent asked to "find recent enterprise leads in fintech with open opportunities" may call SHOW TABLES, then inspect columns, then try a join, then recover from a schema mistake. Those calls do not answer the user; they only discover the system.

2b. Resources as Content Catalogs

Expose database schemas, API hierarchies, and documentation trees as MCP Resources. The model reads the catalog as a navigable map, then writes a precise query or tool call in its first execution step.

{
  "uri": "db://crm/schema",
  "name": "CRM database schema",
  "description": "Use before CRM queries. Lists tables, join keys, allowed filters, and column definitions.",
  "mimeType": "application/json",
  "contents": [{
    "mimeType": "application/json",
    "text": "{\"tables\":{\"leads\":{\"columns\":{\"id\":\"uuid\",\"company\":\"text\",\"industry\":\"text\",\"account_id\":\"uuid\"}},\"opportunities\":{\"columns\":{\"id\":\"uuid\",\"account_id\":\"uuid\",\"stage\":\"text\",\"amount\":\"numeric\"}}},\"joins\":[\"leads.account_id = opportunities.account_id\"]}"
  }]
}

With that Resource in context, the agent can plan: read db://crm/schema, identify leads.account_id = opportunities.account_id, then call the CRM query tool once with the correct join.

3. Selection Reliability: MCP vs. Built-in Tools

Descriptions are the primary mechanism for tool selection. If an agent incorrectly prefers a built-in tool such as Grep over a specialized MCP tool, the first fix is not to remove Grep; it is to improve the MCP tool description.

3a. Description Discipline

A strong description states the tool's unique capability, expected input format, output shape, and boundaries.

{
  "name": "SemanticSearch",
  "description": "Searches indexed product docs by concept, synonym, or meaning when the user does not know the exact wording. Input should be a natural-language concept query such as 'refund abuse risk' or 'enterprise SSO setup'. Returns ranked passages with document IDs and relevance scores. Do NOT use for exact string, filename, or symbol matches; use Grep for literal text."
}

3b. Disambiguation

Use SemanticSearch for concept-based questions like "where do we describe account takeover risk?" Use Grep for exact strings like "Invalid Token", function names, exported symbols, filenames, and stack trace fragments.

4. Structured Error Propagation

Tools must return metadata that enables an agent or coordinator to make intelligent recovery decisions.

• isError: set true when the tool failed. Do not use it for valid empty results.
• errorCategory: standardize categories such as TRANSIENT, VALIDATION, and PERMISSION.
• isRetryable: set true only when retrying could plausibly succeed.
• Recovery vs. failure: distinguish an access failure from a valid empty result. An access failure may require a pivot or user-facing explanation; an empty result is a successful query with no matches.

{
  "isError": true,
  "errorCategory": "PERMISSION",
  "isRetryable": false,
  "message": "Database user lacks SELECT permission on opportunities. Ask an admin for crm.opportunities:read."
}

{
  "isError": false,
  "rows": [],
  "message": "Query succeeded; no matching leads found."
}

Lab Exercise: Designing a High-Reliability MCP Integration

Objective: master MCP configuration, description engineering, Resources, and structured error handling.

1. Secure configuration: create a project-level .mcp.json file that connects to a mock database server using ${DB_PASSWORD} for environment variable substitution.
2. Catalog implementation: define an MCP Resource at db://crm/schema that lists available tables and column definitions. Verify that the agent uses this Resource to plan a complex join before calling tools.
3. Description engineering: given built-in Grep and custom SemanticSearch, rewrite the SemanticSearch description so the agent chooses it for concept-based queries but continues using Grep for exact string matches.
4. Error handling: implement a "Permission Denied" response with isError: true, errorCategory: "PERMISSION", and isRetryable: false. Verify the agent informs the user instead of attempting a redundant retry.
5. ZDR compliance audit: if the architecture uses the MCP Connector, document that the workflow is not ZDR-eligible because the connector requires server-side routing.