REDCap API Toolkit

Documentation, a machine-readable specification, and an MCP server for the REDCap API.

Component	Contents	Location
Method reference	All 55 API methods, one page each: parameters, permissions, safety notes, curl and Python examples	docs/methods/
Guides	Getting started, core concepts, data model, troubleshooting, security, destructive-operation safety, recipes, client-library overview	docs/
Specification	Every method, parameter, enum, default, permission, and safety level as structured JSON, with a JSON Schema	spec/redcap-api.json
MCP server	Documentation tools requiring no token, plus live API access that is read-only by default	mcp-server/
Examples	Minimal curl, Python, R, and Node clients	examples/
Agent orientation	Condensed reference for LLM agents	docs/agent-guide.md · llms.txt

Documented against REDCap 16.0.39. The spec records the version it was verified against.

Request model

The API is a single endpoint: POST https://YOUR-REDCAP/api/ with application/x-www-form-urlencoded parameters. There are no REST paths and no GET requests. The content parameter (with action on some methods) selects one of 55 methods; a per-project, per-user 32-character token authenticates every call. The default response format is XML; pass format=json&returnFormat=json explicitly.

curl -sS -X POST "https://YOUR-REDCAP/api/" \
  -d token="$REDCAP_TOKEN" -d content=version
# → 16.0.39

See Getting started and the method catalog.

MCP server

npx redcap-api-mcp

{
  "mcpServers": {
    "redcap": {
      "command": "npx",
      "args": ["redcap-api-mcp"],
      "env": {
        "REDCAP_URL": "https://YOUR-REDCAP/api/",
        "REDCAP_TOKEN": "<32-char project token>"
      }
    }
  }
}

• The documentation tools (redcap_api_overview, redcap_api_search, redcap_api_docs) require no token.
• Live tools are read-only by default: redcap_export_records, redcap_project_snapshot, and redcap_call (any of the 55 methods, validated against the spec). Write methods require REDCAP_ALLOW_WRITES=true; destructive methods (deletes, data-dictionary replacement, overwriteBehavior=overwrite) additionally require REDCAP_ALLOW_DESTRUCTIVE=true.
• Includes MCP tool annotations, resources (redcap://spec, redcap://overview), and a project-exploration prompt.

See mcp-server/README.md.

Specification

spec/redcap-api.json describes all 55 methods: selectors, parameters (types, enums, defaults, required flags), token type, permissions, safety level (read/write/destructive, with development-status-only flags), and return shapes. It validates against spec/schema.json and is suitable for client generation, call validation, retrieval, and coverage audits.

Safety levels

Level	Methods	MCP gate
Read	28	none
Write	18	REDCAP_ALLOW_WRITES=true
Destructive	9	additionally REDCAP_ALLOW_DESTRUCTIVE=true; several methods are refused by REDCap outside Development status

Before structural changes, export a backup (Export Project XML). See docs/safety.md.

Status and scope

This is an independent project, not affiliated with Vanderbilt University or the REDCap consortium. All documentation is original prose; method facts were verified against official REDCap 16.0.39 documentation. The canonical reference is each instance's API help page and API Playground.

Client libraries: PyCap (Python), REDCapR and redcapAPI (R), PHPCap, redcap-api (.NET). See docs/ecosystem.md.

Contributing

See CONTRIBUTING.md. For a newer REDCap version with changed behavior, open an issue with the method slug and the difference.

License

MIT. REDCap itself is licensed software of Vanderbilt University; using the API requires access to a licensed REDCap instance.