Agentic Workshop
Module 06 · 55 min

MCP: Connect tools and sources

Course by Nello Castellano

MCP offers a contract between an AI client and servers that expose tools or resources. The value is not “connecting everything,” but making capabilities and data explicit, inspectable, and task-bound.

Lessons

What you will tackle, step by step

6.1

Clients, servers, tools, resources and prompts

MCP, Model Context Protocol, is a contract that allows an application with an agent to discover and use external capabilities in a structured way. To think about it properly you have to separate who asks, who exposes the capability and the system that actually does the job.

The client manages the agent session. The MCP server can expose tools, resources and prompts: a tool performs an operation with structured input, a resource provides readable content, a prompt offers a reusable request. In Claude Code you can recall resources with `@`; MCP prompts appear as commands.

The downstream service, such as GitHub or a filesystem, can be behind the server. Vague names and incomplete schemas increase incorrect calls even if the connection works. With Tool Search, Claude Code discovers complete schemas when needed: precise descriptions therefore remain essential.

See it in practice · Answer a question about the availability of a part

An operator asks if the spare part `BRK-204` is available and what return policy applies. The warehouse business system remains behind an MCP server.

  1. The client discovers `getInventory`, a read-only tool with mandatory input `sku`, and `return-policy`, a versioned textual resource with no client data.
  2. The agent uses the resource to read the general conditions, then proposes the call to `getInventory` with only the code `BRK-204`.
  3. The server validates the code, queries the business system and returns quantity, location and time of the data; it does not expose internal credentials or queries.
  4. If the business system does not respond, the tool returns `service_unavailable` and no estimated quantity; the operator sees that availability has not been verified.

Result: Return policy and stock availability remain two distinct, discoverable capabilities. The agent can cite the source it read and does not turn a warehouse error into a made-up response.

6.2

Local or remote: a trust decision

Local and remote do not just describe where an MCP server runs. They describe a boundary of trust: what data leaves the machine, which identity can read it, and which service you depend on to continue working.

A local server normally uses a `stdio` process; a remote server normally uses HTTP. Local does not mean offline: that process can still call the Internet. A remote server centralizes updates and availability, but sends data across the machine boundary. Evaluate provenance, transmitted data, latency and behavior when the service does not respond.

Draw the boundary before configuration: what data goes out, who receives it, how long does it exist and which identity authorizes the operation?

See it in practice · Search for clauses in confidential contracts

The legal team wants to look for renewal terms in a client contract folder. A remote service would be easier to update, but would receive the text of the documents.

  1. Classify data and track the flow: queries, contract extracts, customer names, logs and results. Confirm that documents are not allowed to exit the machine.
  2. Choose a read-only local server, confined to the approved folder; exclude attachments, temporary folders and symbolic links directed elsewhere.
  3. Expose `searchClauses` with query and limit results; returns relative path, short excerpt and page, without copying the complete document to the log.
  4. Turn off the network during the test, try an excluded path and simulate an unreadable PDF; verify that each error is distinct and that no files are modified.

Result: Research remains useful without transferring contracts. The cost of local management is explicit and the perimeter is tested even in cases of error.

6.3

Minimum scope and tokens

A token is a credential that represents an identity and permitted operations. Scopes are the associated permissions. The rule of thumb is simple: allow the minimum capability needed for the minimum time needed.

A token must not be more powerful than the task. To read issues you don't need to create branches or administer the repository. Narrow scopes limit the damage if the credential is stolen, the server is compromised, or a request is manipulated.

Do not show tokens in logs, shared configs, or screenshots. Plan for rotation and revocation. The agent must be able to explain what capability each permission requires.

See it in practice · Read open incidents without administering the service

An operator prepares the morning briefing by reading the title, severity and status of incidents. You don't have to close them, change shifts or see billing information.

  1. List only the necessary calls: list of incidents and details of an incident in the production environment; no writing operations.
  2. Create a dedicated service identity with `incidents:read`, short expiration and access to the affected project only; keep the token in the secret store.
  3. Configure the server to filter the returned fields and mask any personal data in the notes before passing them to the client.
  4. Valid read test, closure attempt and token revoked: the first succeeds, the second is denied, the third produces an authentication error without printing the credential.

Result: The briefing contains what is needed, while a wrong call cannot change the status of incidents. Revocation was tested before depending on the link.

6.4

Handshake, minimal test, and diagnosis

When an MCP link doesn't work, "the server is broken" is too broad a conclusion. The call goes through multiple layers and each can fail differently: process, setup, discovery, authentication, validation, and downstream service.

The handshake is the initial greeting with which client and server agree on the protocol version and capabilities. Then check the connection layer by layer: configuration read, process or endpoint reachable, initialization successful, capabilities available, valid authentication, and minimal successful call. In Claude Code, `/mcp` shows server status and authentication.

Logs must show capability names, times, and errors without revealing secrets. If a tool is visible but fails, compare the argument schema and scope before switching servers.

  1. Start and verify that the server process is reachable.
  2. Check that the client reads the expected configuration.
  3. Inspect discovered tools, resources, and related schemas.
  4. Make a read-only call with known input.
  5. Record the failure result, duration and boundary without exposing token.
See it in practice · Diagnose an order connector that does not show `getOrder`

The client declares the connection active, but the agent does not see the tool that should retrieve a test order.

  1. Check the process with a health prompt and confirm that the client is using the test environment's configuration file, not a previous copy.
  2. Request the list of capabilities: you find that the server publishes `get_order`, while the documentation and client expect `getOrder`.
  3. Align name and schema, restart only the necessary component and verify the discovery before touching token or order service.
  4. Perform a read on the dummy order `TEST-104`; records duration and status. Then test blank ID and unavailable service to confirm distinct, secret-free errors.

Result: Failure is attributed to capability discovery, not authentication. The fix is small and the test suite makes any subsequent issues visible.

Guided example

Read-only issue reader

Task Notes uses public issues as backlog, without modifying the remote repository.

Server: verified remote repository
Tools: listIssues, getIssue
Scope: contents:read, issues:read
Excluded: createIssue, push, merge, admin
Proof: retrieve a known issue and record the response time