A prescribed tool is a tool that maps to a specific GraphQL operation in a persisted document. The @tool(prescribed:) argument links the tool definition to an operation name in a persisted document. This approach provides a structured way to expose specific GraphQL operations as tools that can be called by AI models.
IBM API Connect for GraphQL lets you build a GraphQL layer over any REST API — and then expose individual operations from that layer as typed, documented MCP tools that AI models can call directly. This sample demonstrates that end-to-end pattern by wrapping a real, live REST API — the National Weather Service (NWS) API — using the @rest directive and @sequence directive to compose multiple REST calls into a single GraphQL operation, which is then published as a prescribed MCP tool.
Overview
The sample implements a weather forecast service backed by the public NWS API. The schema chains two REST calls together:
getPoint — resolves latitude/longitude coordinates to an NWS grid point (gridId, gridX, gridY).getPointForecast — fetches the detailed forecast periods for that grid point.getForecast — a composed query using @sequence that calls both in order, passing gridId from step one into step two automatically.
The getForecast operation is then exposed as a prescribed MCP tool called weather-lookup.
Schema Structure
The schema consists of three files:
1. stepzen.config.json
Declares the StepZen endpoint name that this schema is deployed to:
{
"endpoint": "api/weather-mcp-tools"
}
This value determines the URL path under which the GraphQL API and MCP endpoint are served after stepzen deploy.
2. index.graphql
Defines the schema declaration, all GraphQL types, and the three query resolvers:
"""
Schema of the Weather API that gives weather forecast data
"""
schema
@sdl(
files: []
executables: [{ document: "operations.graphql", persist: true }]
)
@tool(name: "weather-lookup", prescribed: "GetForecast") {
query: Query
}
"""
The type that represents a weather grid point in the National Weather Service API
"""
type Point {
"""
The ID of the NWS office grid
"""
gridId: String!
"""
X-coordinate in the NWS grid system
"""
gridX: Int!
"""
Y-coordinate in the NWS grid system
"""
gridY: Int!
"""
Information about the nearest city/location
relationship Links Point to location information
"""
relativeLocation: RelativeLocation
}
"""
The type that contains location properties for a weather point
"""
type RelativeLocation {
"""
Location properties including city and state
"""
properties: Properties1
}
"""
The type that represents the Location properties for a weather point
"""
type Properties1 {
"""
City name
"""
city: String
"""
State name
"""
state: String
}
"""
The type that describes the Weather forecast for a specific time period
"""
type Forecast {
"""
Sequence number of the forecast period
"""
number: Int!
"""
Name of the forecast period (e.g., "Tonight", "Monday")
"""
name: String!
"""
Start time of the forecast period
"""
startTime: DateTime!
"""
End time of the forecast period
"""
endTime: DateTime!
"""
Forecasted temperature
"""
temperature: Float!
"""
Unit of temperature measurement (F or C)
"""
temperatureUnit: String!
"""
Temperature trend information (rising, falling, or null)
"""
temperatureTrend: JSON
"""
Brief forecast
"""
shortForecast: String!
"""
Detailed forecast
"""
detailedForecast: String!
"""
URL to an icon representing the forecast conditions
"""
icon: String!
}
type Query {
"""
The query that gets a weather grid point from latitude and longitude using the source National
Weather Service API and returns Point object with grid information.
lat paramter is the Latitude coordinate.
lng parameter is the Longitude coordinate.
"""
getPoint(lat: Float!, lng: Float!): Point
@rest(
endpoint: "https://api.weather.gov/points/$lat;,$lng",
resultroot: "properties"
)
"""
The query that gets forecast data for a specific NWS grid point and returns Array of Forecast objects
office parameter is the NWS office identifier.
gridX parameter is the X-coordinate in the grid.
gridY parameter is the Y-coordinate in the grid.
"""
getPointForecast(office: String!, gridX: Int!, gridY:Int!): [Forecast!]!
@rest(
endpoint: "https://api.weather.gov/gridpoints/$office/$gridX;,$gridY/forecast",
resultroot: "properties.periods[]"
)
"""
The query gets weather forecasts for a location using lat/lng coordinates and returns Array of Forecast objects.
lat parameter is the Latitude coordinate.
lng parameter is the Longitude coordinate.
In this query, First gets grid point, then uses that to get forecast
"""
getForecast(lat: Float!, lng: Float!): [Forecast!]!
@sequence(
steps: [
{
query: "getPoint"
},
{
query: "getPointForecast", arguments:[
{
name: "office"
field: "gridId"
}
]
}
]
)
}
3. operations.graphql
Contains the persisted GraphQL operation that is exposed as the MCP tool:
"""
Get weather forecast for a location by latitude and longitude
This operation first resolves the NWS grid point for the coordinates and then
returns the full array of forecast periods (typically covering the next 7 days)
"""
query GetForecast(
"""Latitude coordinate of the location"""
$lat: Float!,
"""Longitude coordinate of the location"""
$lng: Float!
) {
getForecast(lat: $lat, lng: $lng) {
number
name
startTime
endTime
temperature
temperatureUnit
temperatureTrend
shortForecast
detailedForecast
icon
}
}
How the @sequence Directive Works
The getForecast query uses the @sequence directive to chain two REST-backed queries together. APIConnect For GraphQL executes the steps in order and automatically pipes output fields from one step into the input arguments of the next:
getForecast(lat: Float!, lng: Float!): [Forecast!]!
@sequence(
steps: [
{ query: "getPoint" },
{
query: "getPointForecast",
arguments: [
{ name: "office", field: "gridId" }
]
}
]
)
- Step 1:
getPoint(lat, lng) calls https://api.weather.gov/points/$lat;,$lng and returns a Point object with gridId, gridX, and gridY.
- Step 2:
getPointForecast(office, gridX, gridY) calls https://api.weather.gov/gridpoints/$office/$gridX;,$gridY/forecast. The office argument is mapped from the gridId field returned in step 1. gridX and gridY are passed through automatically by name-matching.
How Prescribed Tools Work
The @tool directive at the schema level registers the GetForecast operation from the persisted document as an MCP tool:
@tool(name: "weather-lookup", prescribed: "GetForecast")
name — the identifier that AI models will use to invoke the tool.prescribed — the name of the GraphQL operation in the persisted document to bind to.
The operation's docstring and variable descriptions (introduced in GraphQL September 2025) are used to generate the tool's description and input schema automatically.
MCP Tool Description
When deployed, APIConnect For GraphQL generates the following MCP tool definition from the operation's descriptions:
{
"name": "weather-lookup",
"description": "Get weather forecast for a location by latitude and longitude. This operation first resolves the NWS grid point for the coordinates and then returns the full array of forecast periods (typically covering the next 7 days)",
"inputSchema": {
"type": "object",
"properties": {
"variables": {
"properties": {
"lat": {
"description": "Latitude coordinate of the location",
"type": "number"
},
"lng": {
"description": "Longitude coordinate of the location",
"type": "number"
}
},
"required": ["lat", "lng"],
"type": "object"
}
},
"required": ["variables"]
}
}
Deploying and Using the Tool
Deploy
stepzen deploy
Connect to Claude Desktop
Follow the Connect Claude Desktop to an MCP server guide and point it at your APIC Connect For GraphQL's MCP endpoint (configured in stepzen.config.json as api/weather-mcp-tools)
For Eg: https://<env_name>.us-east-a.ibm.stepzen.net/api/weather-mcp-tools/mcp
Example Interactions
Once connected, an AI model can ask questions like:
- "What is the weather forecast in New York ?" — the model will infer the lat/lng coordinates and call
weather-lookup.
Sample prompt executed using Claude Desktop
Benefits of Prescribed Tools
- Controlled Access: Only specific, predefined operations are exposed as tools, giving fine-grained control over what AI models can execute.
- Type Safety: The GraphQL schema validates all inputs and outputs before they reach the underlying API.
- Clear Documentation: Operation and variable descriptions serve as both developer documentation and AI model instructions.
- Composability: Complex multi-step API workflows (like this two-call NWS sequence) are hidden behind a single, simple tool interface.