{ "cells": [ { "cell_type": "markdown", "metadata": { }, "source": [ "*Module 7 Self-Driven Lab*\r\n", "\r\n", "# MCP Mastery: Scoping, Catalogs, and Errors\r\n", "\r\n", "**Objective:** master MCP configuration, description engineering, Resources, and structured error handling.\r\n", "\r\n", "## Challenge Outline\r\n", "\r\n", "Build a complete notebook that demonstrates the following outcomes:\r\n", "\r\n", "- **Secure configuration:** create a project-level `.mcp.json` file that connects to a mock database server using `${DB_PASSWORD}` for environment variable substitution.\r\n", "- **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.\r\n", "- **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.\r\n", "- **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.\r\n", "- **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.\r\n", "\r\n", "Your solution should include enough code, output, or written observations to prove each outcome worked. Keep the notebook focused on final behavior and evidence rather than a guided walkthrough.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "## Student Workspace\n", "\n", "Use the sections below to build your solution. Each section maps to one required outcome from the challenge outline.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 1: Secure configuration\n", "\n", "create a project-level `.mcp.json` file that connects to a mock database server using `${DB_PASSWORD}` for environment variable substitution.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 1: Secure configuration\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 2: Catalog implementation\n", "\n", "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.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 2: Catalog implementation\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 3: Description engineering\n", "\n", "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.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 3: Description engineering\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 4: Error handling\n", "\n", "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.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 4: Error handling\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Part 5: ZDR compliance audit\n", "\n", "if the architecture uses the MCP Connector, document that the workflow is not ZDR-eligible because the connector requires server-side routing.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Part 5: ZDR compliance audit\n", "# Add your implementation, outputs, or notes here.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "### Verification Notes\n", "\n", "Summarize the evidence that each part worked. Capture API signals, validation outcomes, errors, recovery behavior, cost observations, or comparisons required by this lab.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { }, "outputs": [ ], "source": [ "# Verification notes\n", "# Record the evidence that proves each lab outcome worked.\n" ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "---\n", "\n", "## Answer Key\n", "\n", "The cells below contain the completed reference implementation/content for this module. Use this section only after attempting the self-driven lab." ] }, { "cell_type": "markdown", "metadata": { }, "source": [ "*Module 7 of 12*\n", "\n", "# MCP Mastery: Scoping, Catalogs, and Errors\n", "\n", "This module shifts from basic connectivity to strategic integration of Model Context Protocol (MCP) servers into production agentic workflows and team development environments. The focus is Task 2.4 and Task 2.1: scope MCP servers correctly, reduce exploratory discovery calls with Resources, engineer tool descriptions for reliable selection, and propagate structured errors the coordinator can recover from.\n", "\n", "\n", "## 1. Administrative Scoping \u0026 Credential Security\n", "\n", "Orchestrators must manage tool availability at both personal and project levels while protecting sensitive credentials.\n", "\n", "- **Project-scoped servers (`.mcp.json`):** use for standardized team tooling shared through version control. Commit the server definition, not secrets.\n", "- **User-scoped servers (`~/.claude.json`):** use only for personal, local, or experimental servers that should not be shared with the team.\n", "- **Secure credential management:** never hardcode secrets. Use environment variable expansion such as `${GITHUB_TOKEN}` or `${DB_PASSWORD}` so the server authenticates at runtime from the local environment.\n", "- **Community vs. custom servers:** prefer existing community MCP servers for standard integrations like Jira or Slack. Reserve custom servers for proprietary, team-specific logic that community servers cannot express.\n", "\n", "*.mcp.json*\n", "```json\n", "{\n", " \"mcpServers\": {\n", " \"crm-db\": {\n", " \"command\": \"node\",\n", " \"args\": [\"./mcp-servers/mock-db-server.js\"],\n", " \"env\": {\n", " \"DB_HOST\": \"${DB_HOST}\",\n", " \"DB_USER\": \"${DB_USER}\",\n", " \"DB_PASSWORD\": \"${DB_PASSWORD}\"\n", " }\n", " }\n", " }\n", "}\n", "```\n", "\n", "\u003e **Tip.** Architect Tip for the Exam\n", "If the whole team should use the same integration, start with project-level `.mcp.json`. If the server is personal, experimental, or tied to private credentials, keep it in `~/.claude.json`.\n", "\n", "## 2. Reducing the Discovery Tax with MCP Resources\n", "\n", "Agents should plan tool sequences using navigable catalogs rather than burning tokens on exploratory trial-and-error calls.\n", "\n", "### 2a. The Discovery Tax\n", "\n", "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.\n", "\n", "### 2b. Resources as Content Catalogs\n", "\n", "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.\n", "\n", "*MCP Resource: db://crm/schema*\n", "```json\n", "{\n", " \"uri\": \"db://crm/schema\",\n", " \"name\": \"CRM database schema\",\n", " \"description\": \"Use before CRM queries. Lists tables, join keys, allowed filters, and column definitions.\",\n", " \"mimeType\": \"application/json\",\n", " \"contents\": [{\n", " \"mimeType\": \"application/json\",\n", " \"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\\\"]}\"\n", " }]\n", "}\n", "```\n", "\n", "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.\n", "\n", "## 3. Selection Reliability: MCP vs. Built-in Tools\n", "\n", "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.\n", "\n", "### 3a. Description Discipline\n", "\n", "A strong description states the tool\u0027s unique capability, expected input format, output shape, and boundaries.\n", "\n", "*SemanticSearch description*\n", "```json\n", "{\n", " \"name\": \"SemanticSearch\",\n", " \"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 \u0027refund abuse risk\u0027 or \u0027enterprise SSO setup\u0027. Returns ranked passages with document IDs and relevance scores. Do NOT use for exact string, filename, or symbol matches; use Grep for literal text.\"\n", "}\n", "```\n", "\n", "### 3b. Disambiguation\n", "\n", "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.\n", "\n", "## 4. Structured Error Propagation\n", "\n", "Tools must return metadata that enables an agent or coordinator to make intelligent recovery decisions.\n", "\n", "- **`isError`:** set `true` when the tool failed. Do not use it for valid empty results.\n", "- **`errorCategory`:** standardize categories such as `TRANSIENT`, `VALIDATION`, and `PERMISSION`.\n", "- **`isRetryable`:** set `true` only when retrying could plausibly succeed.\n", "- **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.\n", "\n", "*permission denied tool response*\n", "```json\n", "{\n", " \"isError\": true,\n", " \"errorCategory\": \"PERMISSION\",\n", " \"isRetryable\": false,\n", " \"message\": \"Database user lacks SELECT permission on opportunities. Ask an admin for crm.opportunities:read.\"\n", "}\n", "```\n", "\n", "*valid empty result*\n", "```json\n", "{\n", " \"isError\": false,\n", " \"rows\": [],\n", " \"message\": \"Query succeeded; no matching leads found.\"\n", "}\n", "```\n", "\n", "## Lab Exercise: Designing a High-Reliability MCP Integration\n", "\n", "**Objective:** master MCP configuration, description engineering, Resources, and structured error handling.\n", "\n", "1. **Secure configuration:** create a project-level `.mcp.json` file that connects to a mock database server using `${DB_PASSWORD}` for environment variable substitution.\n", "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.\n", "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.\n", "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.\n", "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.\n", "\n", "\u003e **Tip.** Architect Tip for the Exam\n", "MCP reliability is not just connectivity. The architecture is reliable when server scope is intentional, secrets are externalized, Resources reduce exploratory calls, descriptions make tool choice obvious, and error metadata tells the agent whether to retry, pivot, or inform the user." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.0" } }, "nbformat": 4, "nbformat_minor": 5 }