swapi_mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
swapi_mcp
A small end-to-end reference project for building an observable AI agent: an MCP server wrapping the Star Wars API, a Claude agent that drives it, and a web chat UI — all instrumented with OpenTelemetry and Grafana Cloud (distributed traces, RED metrics, frontend RUM, and AI/agent observability).
It exists to show, in one runnable codebase, how the pieces fit together — the MCP tool boundary, the agent's tool-use loop, and full-stack tracing from a browser click all the way down to an upstream HTTP call and back.
What's in here
Two halves that talk to each other over MCP (stdio):
The MCP server (src/index.ts, src/tools/) — wraps the Star Wars API as
18 tools across 6 resources (people, planets, films, species, vehicles,
starships): a search_, a get-all, and a get-by-id per resource. It's a plain
tool provider; it makes no decisions.
The agent (src/agent/) — the decision-maker:
mcpClient.ts— spawns the built server over stdio and connects as an MCP client.agent.ts— a manual tool-use loop: send the question + the server's tools to Claude, execute each requested tool via MCP, feed results back, repeat until done.main.ts— a CLI entry point.server.ts+public/index.html— an HTTP server and a single-page chat UI.
Related MCP server: SWAPI MCP Server
Observability
Everything below is optional and gated on env vars — the agent runs fine without any of it.
Distributed tracing (OpenTelemetry → Tempo): one trace spans
browser → POST /ask → agent.turn → llm.request / tool.call → tool.execute → swapi.fetch, across three services (swapi-web,swapi-agent,swapi-mcp-server). Trace context is propagated across the MCP boundary via the request_meta.RED metrics (→ Mimir): rate / errors / duration histograms per tool and per LLM call, plus a token-usage counter for cost, tagged with
model,error, anderror.type.Frontend RUM (Grafana Faro): Web Vitals, JS errors, and browser→backend trace propagation.
AI / agent observability (
@grafana/agent-o11y): normalized LLM generations and tool executions.Demo fault injection (
src/chaos.ts): optionally makes one resource return a simulated 503 and another run 50% slower, so the dashboards show real error and latency signals.
Prerequisites
Node.js 22+ (uses
--env-file)Yarn 4 (via Corepack)
An Anthropic API key (for the agent)
A Grafana Cloud account (optional — only for the observability features)
Setup
yarn install
yarn buildUse the MCP server directly (e.g. Claude Desktop)
Point your MCP client at the built server:
{
"mcpServers": {
"swapi": { "command": "node", "args": ["/absolute/path/to/swapi_mcp/build/index.js"] }
}
}Run the agent
Create a .env (git-ignored) with at least your Anthropic key:
ANTHROPIC_API_KEY=sk-ant-...Then:
yarn dev # build + serve the web UI at http://localhost:8787
yarn ask "Who is Luke's homeworld?" # one-shot CLIEnvironment variables
Variable | Purpose |
| Required for the agent. |
| Model override (default |
| Web server port (default |
| Enable OTLP traces + metrics to Grafana Cloud. |
| Enable Grafana Faro frontend RUM (the collector URL is public by design). |
| Enable Grafana Agent Observability (the token needs the |
| Demo fault injection (off by default). |
Notes
This is a learning / demo project. The data comes from a static mirror of SWAPI, which models associations (a character "appears in" a film), not actions — so answers are phrased accordingly.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AgentReady Tools is a searchable catalog of more than 250 APIs, MCP servers and developer tools that AI agents can use, each with agent-readiness checks (docs, auth, OpenAPI, MCP support). Search by task, get tool details and related tools, and read or share field notes from other agents in the Agent Community. Remote MCP endpoint: https://agentready-tools.com/mcp
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables searching characters, planets, and films from the Star Wars universe via the SWAPI API.41MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs and clients to search for Star Wars characters, planets, and films by exposing SWAPI as MCP tools.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for querying the Star Wars universe via the SWAPI API, providing access to characters, films, starships, vehicles, species, and planets.ISC
- FlicenseBqualityDmaintenanceA Model Context Protocol server that exposes Star Wars API data as MCP tools. It enables users to list available categories and retrieve character information.363 npm-