Developers

MCP server

The Reckn MCP server exposes your workspace to any client that speaks the Model Context Protocol. Upload folders of documents, generate and lock criteria, start runs and pull reports — described in plain language instead of assembled by hand.

What it is

A local process that exposes the Reckn API to your MCP client as tools. The client decides which calls to make; the server executes them against your workspace using your API key. Nothing new is exposed — it is the same API, driven conversationally.

It is most useful for the bulk and ad-hoc work that is tedious through a UI and not worth writing a script for: pushing a folder of fifty proposals through, pulling a batch of reports to disk, checking what failed last night.

Requirements

  • Node.js 18 or later
  • An MCP client
  • A Reckn workspace API key. Create one in the app under Settings → API keys; it starts with rk_.

Install

Install the server's dependencies where the server lives.

Shell
npm install

Register the server

Add the server to your MCP client's configuration. Clients differ in where that file lives and what it is called — check your client's documentation for the path. The entry itself has the same shape everywhere: a command, its arguments, and the environment it runs with.

MCP server entry
{
  "mcpServers": {
    "reckn": {
      "command": "node",
      "args": ["/absolute/path/to/reckn-mcp-server.js"],
      "env": {
        "RECKN_API_BASE": "https://dashboard.reckn.app/api",
        "RECKN_API_KEY": "rk_your_api_key"
      }
    }
  }
}
VariableValue
RECKN_API_BASE The API base URL. Both variables are required — the server exits immediately without them.
RECKN_API_KEY Your rk_ workspace key. Every call is scoped to it, and every call is attributed to it in the activity log.
The key sits in a plain-text file

The config holds a live workspace credential in clear text on your machine. Use a key issued for this purpose so it can be revoked on its own, and revoke it if the machine changes hands.

Restart your client. The server starts automatically.

Screenshot docs/mcp/01-tools-registered.png

Reckn tools available in an MCP client after restart.

Verify

Ask for something read-only first:

Prompt
List my Reckn pipelines.

If your pipelines come back, the key, the base URL and the registration are all correct.

Using it

Describe the outcome. The client works out the calls.

Upload a folder of sources
Upload the folder at /docs/job-descriptions as source documents
for pipeline abc-123
Generate and lock criteria
Generate criteria for criteria set def-456 from those documents,
then lock it
Run an evaluation
Run pipeline abc-123 with criteria def-456 against document ghi-789
Pull a report to disk
Get the report for run jkl-012 as a PDF and save it to /tmp/report.pdf
Video docs/mcp/02-folder-to-report.mp4

A folder of documents uploaded, criteria generated and locked, a run started, and the report saved — all from the client.

Destructive tools exist

The server can delete pipelines, criteria sets, documents and runs. Say what you want deleted explicitly and by ID. "Clean up the old ones" is an instruction the client will interpret, and deletes are recorded but not undone from here.

Tools

Pipelines

ToolWhat it does
list_pipelinesLists the workspace's pipelines
get_pipelineOne pipeline with its criteria, resources, templates and prompts
get_pipeline_templatesReport templates for a pipeline
delete_pipelineRemoves a pipeline from the workspace

Catalog

ToolWhat it does
get_catalogPipeline templates available to add
add_catalog_pipelineAdds a pipeline to the workspace from a template

Criteria

ToolWhat it does
list_criteriaCriteria sets for a pipeline; filters on search and status
get_criteriaOne criteria set in full
create_criteriaCreates a criteria set
update_criteriaUpdates name, description, criteria items, comparisons or weighting fields
delete_criteriaDeletes a criteria set
generate_criteriaGenerates criteria from source documents
generate_criterionGenerates a single additional criterion
lock_criteriaLocks a set against edits
unlock_criteriaReopens a locked set
set_default_criteriaMarks a set as the pipeline default

Weighting

ToolWhat it does
get_criteria_comparisonsThe pairwise comparison matrix
update_comparisonRecords one pairwise comparison
generate_simple_weightsDerives weights, fast path
generate_advanced_weightsDerives weights with finer-grained reasoning

Documents

ToolWhat it does
list_documentsAll documents; filters on pipeline, type and time window
get_documentOne document's metadata
download_documentWrites a document's file to a local path
delete_documentDeletes a document
list_pipeline_documentsDocuments scoped to one pipeline
get_pipeline_documentOne document within a pipeline
delete_pipeline_documentRemoves a document from a pipeline
upload_source_fileUploads one local file as a source document
upload_target_fileUploads one local file as a target document
upload_source_documentsUploads every supported file in a folder as sources, in batches of 10
upload_target_documentsUploads every supported file in a folder as targets, in batches of 10

Runs

ToolWhat it does
list_runsRuns; filters on status, pipeline, run id, search and time window
get_runOne run with criteria, evaluation, decision and summary output
get_run_reportThe run's report as HTML or PDF, optionally saved to disk
get_run_dataRaw execution results
get_run_artifactsThe run's artifact — latest, a specific version, or all versions
create_runCreates and starts a run
retrigger_runRe-runs a failed or completed run
update_runRenames a run
delete_runDeletes a run

Logs

ToolWhat it does
list_activity_logsAudit trail entries
list_usage_logsUsage with token counts and model info

Supported files

.pdf, .docx, .doc, .txt, .rtf, .xlsx, .csv.

A folder upload silently skips anything else — it does not fail. If a file you expected is missing afterwards, check its extension first.

Troubleshooting

SymptomUsual cause
No Reckn tools in the client The client was not restarted, the path in args is not absolute, or dependencies were never installed.
The server exits on start RECKN_API_BASE or RECKN_API_KEY is missing. Both are required.
Every call fails on authorization The key is not an rk_ workspace key, or it has been revoked.
A resource "does not exist" but you can see it in the app The key belongs to a different workspace.
Files in a folder were not uploaded Unsupported extensions are skipped. Per-file errors come back in the result — ask the client what it reported.