Skip to content

A2: Build a small MCP tool server

At a glance

  • Task: build a local MCP server whose tools, schemas and errors help an agent select, call and recover correctly.
  • Week: 2
  • Weight: 2.5 points
  • Due: Sunday 23:59 in the listed week
  • Hand in: the server, a report.json, and outputs from the public protocol check.
  • Done when: selection, valid arguments and one recoverable error each have a real trial and evidence.
  • Time: published after a timed pilot; record your prediction and actual time.

Objectives

Design a small model-readable tool surface and verify its behaviour (LO2). No third-party sign-in or OAuth is required.

Prerequisites

Follow the safety practices in syllabus §9:

  • Run the agent in a dedicated directory or container.
  • Keep residency, employer and cloud credentials out of that environment.
  • Keep keys out of repositories, prompts, screenshots and logs.
  • Run injection demonstrations offline against the local machine only.

Use the mature coding-agent seat supplied for the course. Do not run an unknown generated command on a credential-bearing host.

Tasks

  1. Specify. Choose two or three read or write operations and define names, descriptions, required arguments, errors and a safe retry rule.
  2. Generate. Ask the agent to propose handlers and schemas. Review the proposal before placing it in the server.
  3. Verify selection. Run a request where the right tool is distinguishable from its neighbours; record the selected call and result.
  4. Verify arguments. Run a valid call and an invalid-argument call. Check that the server returns structured feedback without a traceback.
  5. Verify recovery. Make one tool return a retryable local error, then show the agent taking the documented next step. Keep all three trials.
  6. Revise. Fix one unclear description or error, rerun the protocol check, and write the decision line.

Generation is the proposed tool design; verification is the protocol transcript and direct result inspection. The check never calls a model and does not turn a transcript into a mark.

Deliverables

Include the server source, schemas, report.json, and protocol output. The report has a server_path naming the submitted tool_server.py and exactly three trial cases: selection, arguments and recovery, each with request, expected, actual, disposition and evidence IDs. Start from starter/ and run:

python practice/a2/protocol_check.py path/to/submission/tool_server.py
python practice/a2/check.py path/to/submission

protocol_check.py is an envelope smoke test. It checks the handshake, the shape of the tool list, one valid call and one refused invalid call. It never calls a model, so it does not show that a model can choose and use your tool; a pass prints that limitation on its own line.

Register the same tool_server.py command in your mature agent's documented local-stdio tool configuration. The three report trials are the real agent runs that establish selection, argument handling and recovery.

Grading

Criteria are model-readable tool descriptions; correct schema validation; structured, bounded errors; recovery evidence; and an explanation of one revision. The public check only detects missing or inconsistent records; it does not claim that a model selected a tool correctly on unseen requests.

AI use rules

Green: drafting schemas and boilerplate. Yellow: proposing descriptions or recovery paths, followed by your own protocol runs. Red: the expected tool, error interpretation and decision are your own. Do not paste private data or keys into prompts or outputs. Attach one AI-use note ID.

Estimated time

Published after a timed pilot. Record predicted and actual time and request help if a local protocol failure is unclear.

Work record outline

A2 report
server_path: TODO
trials: [{case: selection|arguments|recovery, run_kind: real, request: TODO, expected: TODO, actual: TODO, disposition: TODO, evidence: [TODO]}]
protocol_evidence: [TODO]
explanation: TODO
ai_use_note: TODO
decision: accept | narrow | recheck | stop
because: evidence ID(s)
next: TODO