Docs navigation

Guides / Read-only API wrapper

One upstream API, wrapped in a few tools

The simplest shape an MCP server takes: a handful of read-only tools in front of one upstream API, deployed with a single bearer token and no state to manage.

best for
solo devs, small teams
state
none
auth
single token

This is the simplest shape an MCP server takes: a handful of tools, each making one call to a single upstream API and handing back the answer. No writes, no memory between calls, nothing that has to survive a restart. A weather lookup, a docs search, a public transit timetable - the pattern is the same regardless of what sits behind it.

It's the easiest category to deploy, for a concrete reason: there's almost nothing for the platform to get wrong. Point the deploy wizard at a repo and it reads the project itself - finds the manifest, works out the framework and dependency manager, and asks you to confirm what it found rather than configure anything. The only secret this kind of project usually needs is the one API key the upstream service requires, injected as an encrypted environment variable when the container starts. And because a tool like this is typically called by one person, or a few people who trust each other, the single bearer token foro generates on deploy is already the right amount of auth - not a placeholder for something more serious to come later.

$ deploy
  detecting manifest… found tools.py (FastMCP, uv)
  building image… done (38s)
  health check… passing
  live at https://tern-basin-7e2c.foro.sh

That URL is the whole deliverable. It's stable - unchanged by redeploys, independent of which branch happens to be checked out - so it's the kind of thing that gets pasted into an agent's config once and forgotten about. Before trusting a new tool with anything real, the Playground tab in the dashboard is worth a visit: call it directly, watch the actual request and response, confirm it returns real data and not a stack trace, without leaving the browser or writing a test harness for something this small. Once it's live, pushing a fix to main either prompts a one-click redeploy or, with continuous deployment switched on, ships itself.

The same simplicity carries over to auth and monitoring. Auth isn't an integration to plan around - it's one field in the project's settings; the generated token works from day one, and if this ever needs to be shared more widely, switching to OAuth later is a setting flip, not a rebuild. And once it's getting real traffic, the dashboard's Tools tab shows how often next_departure gets called, alongside p95 latency and error counts, without wiring up any monitoring of your own.

used viaAdd the URL to Claude Code's or Cursor's MCP config once and it's in every session from then on.
  • Fits cleanly when the upstream is read-only and one key covers every caller.
  • Starts to strain if different callers need different rate limits or different upstream permissions - that's usually a sign the project has grown into an internal connector.