Single-server MCP, with resources

Larkspur must distinguish a missing server-side credential from an empty search result. You will read an MCP tool response, compare returned error data with protocol error status and decide what prompts and resources the host gives to the model.

Step 1: Inspect content and error status separately

Both projects build one FastMCP weather server and a LangGraph client that talks to it over stdio. Project 01 gives the server a tool, get_weather, and a prompt, compare_weather_prompt. Project 02 swaps the prompt for a resource, file://delivery_log, which reads nine order lines from delivery_log.txt. Lesson 5 of T12.1 explains who chooses each kind; this page is about what each one returns, because the client has to handle every shape.

Recorded with SDK 1.30.0 against copies of the two servers, with no API key set:

Construct the two result shapes locally. An error key in tool content and the protocol isError flag are independent fields.

from mcp.types import CallToolResult, TextContent

returned = CallToolResult(content=[TextContent(type="text", text='{"error": "missing key"}')])
raised = CallToolResult(content=[TextContent(type="text", text="missing key")], isError=True)
print(returned.isError)
print(raised.isError)

Expected output

False
True

Step 2: Compare returned errors with raised failures

Three things in that table catch people out.

• An error returned as data is a success. get_weather catches every failure and returns a dict with an error key, so the result carries isError: false and the model reads the message as weather data. A tool that raises is reported differently: a Larkspur search_handbook that raises ValueError("index not loaded") comes back with isError: true and the text Error executing tool search_handbook: index not loaded, and langchain-mcp-adapters turns that into a ToolMessage with status="error". Raise when the call failed; return data when it worked.
• A list becomes one JSON string. The resource function returns list[str], and FastMCP serialises it as one text block, not one block per line. The client joins the text blocks it receives and pastes the result into a message, so the model sees a JSON array.
• The return type decides the schema. get_weather is typed -> dict, and FastMCP lists it with no outputSchema, so the result has no structuredContent either. A typed return, such as a Pydantic model, gives the client a schema to check results against.

The project 03 copy of the server ships with OPENWEATHERMAP_API_KEY = "{{OPENWEATHERMAP_API_KEY}}". The guard only rejects an empty key or the literal YOUR_OPENWEATHERMAP_API_KEY, so the placeholder passes, the API answers 401, and the tool returns {"error": "Authentication failed…"}, again as a success.

Step 3: Trace what reaches the model

The client decides what reaches the model, and the two projects do it differently:

A prompt's text goes to the agent as if the user had typed it. A resource goes in wrapped as CONTEXT … TASK: <what you asked>, or with a request to acknowledge it and keep it in memory when you give no task; the MemorySaver checkpointer keeps it for the rest of the thread. Both servers read files and are started by relative path (python weather_server.py, Path("delivery_log.txt")), so the client only works when it is run from the project folder.

Step 4: Define the contract for each feature

For Larkspur, the same rules give one decision per feature. search_handbook raises when the index is missing and returns chunk ids and text otherwise; the refund policy can be a resource a support engineer attaches by hand; and a prompt like T12.1's answer_with_citations is something the engineer starts on purpose.

Try it yourself

Call the weather tool with no configured key and inspect both the text block and isError. Check that returning an error dictionary still reports false. Contrast that with a tool that raises, then decide which form the Larkspur client should treat as a failed operation rather than valid evidence.

Practice notebook

Run the complete implementation from the practice material after checking the trace or calculation above. Use its stated environment for live model or server calls; recorded model choices and timings are observations, not guaranteed outputs.

• Single server MCP.
• Single server MCP with.

Continue learning

• Lesson 5 of T12.1.

The code for this lesson is in these notebooks. Colab runs one in your browser: install the packages its first cell imports and set the API keys it reads. To run every notebook as written, clone the repository and use its uv environment.

• Raise when a tool call failed and return data when it worked. A caught error returned as a dict carries isError: false, so the model reads it as a real result.
• FastMCP serialises a returned list as one text block, so the client pastes a single JSON array into the model's message.
• Type the return value to get an outputSchema. A tool typed -> dict gives the client no schema and no structuredContent to check.