Skip to main content
Glama
nmkhan076

FDA MCP Server

by nmkhan076
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

GSA MCP Hackathon — Server Template

A ready-to-run starter for building a Model Context Protocol (MCP) server in Python, plus deployment kits for IBM Cloud (watsonx Orchestrate) and Databricks.

Built with FastMCP and uv. If you have never built an MCP server before, start with QUICKSTART.md.

What is an MCP server?

An MCP server exposes tools (functions the model can call), prompts (reusable conversation starters), and resources (data the model can read) to an AI client such as Claude Desktop, Claude Code, or an agent platform like watsonx Orchestrate. You write the tools; the client's model decides when to call them.

This template gives you a working server with one example of each, so you can replace the examples with your own service and deploy.

Related MCP server: MCP Server Boilerplate

Repo structure

mcp-hackathon-template/
├── README.md                  # This file
├── QUICKSTART.md              # 5-minute clone → run → connect walkthrough
├── main.py                    # Local entry point (uv run python main.py)
├── pyproject.toml             # Package + dependencies (uv)
├── requirements.txt           # Mirror of runtime deps (for buildpack hosts)
├── Dockerfile                 # Container image (streamable-HTTP, port 8080)
├── manifest.yaml              # cloud.gov (Cloud Foundry) deploy
├── server.json                # MCP registry metadata
├── .env.example               # Copy to .env for local dev
├── .github/workflows/ci.yml   # Lint + test on push/PR
├── src/
│   └── example_server/        # ← rename to your service
│       ├── app.py             # Thin entry point: builds FastMCP, picks transport
│       ├── config.py          # Settings from env vars / .env
│       ├── models.py          # Pydantic models & enums for tool params
│       ├── utils.py           # Shared helpers (HTTP client, pagination)
│       ├── routes.py          # HTTP-only routes (/health, /version)
│       ├── tools/             # ONE FILE PER TOOL
│       │   ├── __init__.py    #   register_tools(mcp) aggregator
│       │   └── example_tool.py
│       ├── prompts/
│       │   ├── __init__.py    #   register_prompts(mcp) aggregator
│       │   └── example.py
│       └── resources/
│           ├── __init__.py    #   register_resources(mcp) aggregator
│           └── example.py
├── tests/                     # Import + registration smoke tests
├── eval/                      # Stub → build a Phoenix eval harness (see mcp-eval skill)
└── deploy/
    ├── README.md              # Which deployment kit to use
    ├── ibm/                   # watsonx Orchestrate: 3 kits (see below)
    └── databricks/            # Databricks Apps kit

Getting started

Prerequisites

  • uv — pip install uv or brew install uv

Install and run

cp .env.example .env
uv sync
uv run python main.py

The server starts in stdio mode — it talks JSON-RPC over stdin/stdout, which is how local clients (Claude Desktop, Claude Code) launch it. See QUICKSTART.md to connect a client.

Verify

uv sync --group dev
uv run pytest tests/ -v      # tests
uv run ruff check .          # lint

The one-tool-per-file pattern

Each tool lives in its own file under src/example_server/tools/ and exposes a register(mcp) function. tools/__init__.py calls each one from a single register_tools(mcp). This keeps the tool list scannable and lets you add or remove an integration by touching two files.

Step 1 — create src/example_server/tools/my_tool.py:

from typing import Annotated
from urllib.parse import quote
from fastmcp import FastMCP

from example_server.utils import fetch_json


def register(mcp: FastMCP) -> None:
    @mcp.tool(
        name="example_get_thing",
        annotations={
            "title": "Get a thing",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": True,
        },
    )
    async def get_thing(thing_id: Annotated[str, "The ID to fetch."]) -> dict:
        """One-line summary. Document the data source, its update cadence,
        and the return shape here — the model reads this docstring."""
        safe_id = quote(thing_id, safe="")
        return await fetch_json(f"things/{safe_id}")

Step 2 — wire it up in tools/__init__.py:

from example_server.tools import example_tool, my_tool

def register_tools(mcp) -> None:
    example_tool.register(mcp)
    my_tool.register(mcp)  # ← add this line

Step 3 — add any API key as a typed field in config.py and document the env var in .env.example.

Prompts (prompts/) and resources (resources/) follow the exact same register(mcp) + aggregator pattern.

Rename the package

Before publishing your server, rename example_server to your service (e.g. census_mcp):

  1. Rename the folder src/example_server/ → src/<your_name>/.

  2. Update pyproject.toml: the [project].name, [project.scripts], and [tool.hatch.build.targets.wheel].packages.

  3. Find-and-replace example_server across src/, tests/, main.py, Dockerfile, and manifest.yaml.

Tool design tips (federal data)

  • Return structured data, not prose. Return dicts/lists with consistent keys and let the model narrate.

  • Document freshness. Federal datasets lag; state the update frequency and "as-of" date in the docstring.

  • Expose pagination. Use PaginationParams / paginate() from utils.py, and return has_more / next_offset.

  • Use explicit timeouts. utils.fetch_json defaults to 30s.

  • Actionable errors. Return an error dict with a hint, not a raw stack trace.

  • Constrain outbound requests. Keep API origins in operator-controlled code or configuration, pass only validated relative paths to fetch_json, and encode path segments. Never pass a tool-supplied URL directly to an HTTP client.

  • Treat redirects and DNS as security boundaries. Redirects are disabled by default. A server that must fetch caller-supplied URLs needs connection-time IP validation on every hop plus network egress controls; a one-time DNS check is not sufficient.

  • Keep sensitive data out of errors and logs. Do not expose or log upstream bodies, headers, full URLs, query strings, credentials, stack traces, SSNs, dates of birth, or addresses.

Deploying

Local development uses stdio. To share your server with an agent platform, deploy it and register it. See deploy/README.md for a chooser, then:

  • IBM watsonx Orchestrate — deploy/ibm/ (three kits: local stdio toolkit, Code Engine build-from-Git, and prebuilt image).

  • Databricks Apps — deploy/databricks/.

Both read the same server code; app.py automatically serves HTTP when the platform injects a port.

Evaluations

Measuring how well an LLM can use your tools is the real test of server quality. This template intentionally does not ship an eval harness — see eval/README.md for how to build one with the mcp-eval skill.

License

MIT. See SECURITY.md for the vulnerability disclosure policy and hackathon security notes.

Available Tools

1 tool
example_search_datasetsSearch Datasets (example)B
Read-onlyIdempotent

Search federal datasets matching a query string. (STUB — replace me.)

This stub shows the shape of a real tool without calling a live API. Swap the body for an actual request using fetch_json(...); a worked pattern is included below in a comment.

NameRequiredDescriptionDefault
queryYesKeywords to search dataset titles and descriptions.
paginationNoOptional limit/offset (defaults to limit=20, offset=0).
response_formatNoReturn machine-readable JSON (default) or human-readable Markdown.json

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false) already establish the safety profile. The description adds one meaningful behavioral fact—'This stub... without calling a live API'—which is honest and useful context. However, it doesn't elaborate on return behavior, result ordering, or error conditions, leaving most of the behavioral burden on the annotations. No contradiction with the annotations is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is short and front-loads the meaningful description, which is good. However, roughly three of four lines are implementer-facing stub notes ('(STUB — replace me.)', 'Swap the body...', 'a worked pattern is included below in a comment') that add no value to an agent selecting or invoking the tool. It's not verbose, but those sentences could earn their place better with functional detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, return values don't need explanation. The schema plus annotations cover the mechanical calling contract well. However, the description leaves open real-world questions an agent might face, such as what 'federal datasets' covers, and pagination behavior. For an explicitly stubbed example tool, this is adequate, but not complete for a production tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema thoroughly documents all three parameters: the required 'query', the pagination object with limits and defaults, and the response_format enum with its default. Per calibration rules, the baseline is 3 when the schema covers everything. The description itself adds no parameter-level insight, which is acceptable at this coverage level.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Search federal datasets matching a query string' uses a specific verb and resource, so an agent immediately knows what the tool does. The remaining stub text is implementer-oriented but does not obscure the purpose. It earns a 4 because it's clear on function, though the nonsensical stub placeholder text prevents a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, what input it expects conceptually (beyond schema), or any prerequisites or limitations. The stub text discusses implementation ('Swap the body for an actual request') rather than agent-facing usage. While the absence of sibling tools lowers the need for differentiation, the description still provides no real usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedexample_search_datasets
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

C2.9/5.0

Scored across 1 tool

Disambiguation4/5

With only one tool, there is no risk of confusing it with another. However, the tool is a stub named 'example_search_datasets' and described as a placeholder, which reduces clarity about its actual purpose in the FDA domain.

Naming Consistency3/5

There is only one tool, so no pattern can be established or violated. The name 'example_search_datasets' uses snake_case and follows a verb_noun structure, but the 'example_' prefix signals a placeholder rather than a production tool, which is a deviation from typical naming conventions.

Tool Count1/5

A single tool is drastically insufficient for an FDA MCP server, which would be expected to cover drugs, foods, devices, recalls, adverse events, and more. One stub tool represents an extreme mismatch with the domain's scope.

Completeness1/5

The surface contains only a search stub with no detail retrieval, no list operations, no filters beyond a query string, and no other lifecycle operations. This is severely incomplete for any meaningful FDA data access.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Server Boilerplate

    cds-id
    A
    license
    D
    quality
    D
    maintenance
    A ready-to-use starter implementation of the Model Context Protocol (MCP) server that enables applications to provide standardized context for LLMs with sample resources, tools, and prompts.
    2
    3 npm
    1
    MIT

  • MCP Server on Cloudflare

    TedTschopp
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    A deployable MCP server for Cloudflare Workers or Azure Functions that provides example tools (time, echo, math), prompt templates for code assistance, and configuration resources. Enables AI assistants to interact with edge-deployed services through the Model Context Protocol.
    -

  • MCP Template

    xcollantes
    A
    license
    B
    quality
    D
    maintenance
    A template repository for building Model Context Protocol (MCP) servers that enable LLM clients to interact with custom tools and services through standardized JSON-RPC communication.
    3
    MIT