SwiftCNSDocs

Reference

MCP server reference

Endpoint, authentication, permissions, and every SwiftCNS MCP tool grouped by method step.

Before you start

  • Endpoint: https://api.swiftcns.ai/mcp (streamable HTTP). The app shows the URL for your environment under Settings → MCP client access.
  • Auth: OAuth 2. Your client opens a sign-in page; access tokens last up to 5 minutes and refresh automatically.
  • Scopes: cns:read (Read CNS), cns:write (Update CNS), cns:decide (Make decisions), cns:sources:read (Read connected sources).

Steps

How an agent should drive a conversation:

  1. Find scope

    list_workspaces, list_projects. To start: generate_resource_id, create_project, create_conversation.

  2. Read the position

    get_conversation_progress returns the stage, active Action Requests, actionOperations (ready-to-submit tools), permittedTransitionIds and nextTransitionId.

  3. Talk or submit

    Ordinary input: send_message with a stable requestKey (no parentMessageId on the first message), then poll get_message until execution.status is no longer queued or running. The message status may be requires-action when a card is waiting. Decisions: the tool named in actionOperations, with actionRequestId and contractVersion.

  4. Continue

    Add continueConversation: true and parentMessageId (the request's messageId; for workflow-surface requests, the latest assistant leaf) to get the next agent turn. The receipt's continuationMode says whether one is needed: NONE means the next request is already waiting.

  5. Recover

    If execution.status is FAILED and retryable is true, call retry_response.

  6. Reload

    After every action, read progress again. Tool results, not prose, are the authority.

What you get

Tools by method step:

StepTools
Setuplist_workspaces, list_projects, get_project, create_project, generate_resource_id
Conversationcreate_conversation, open_experiment_conversation, list_conversations, get_conversation, get_conversation_progress, list_conversation_messages, list_conversation_option_sets, send_message, get_message, retry_response, stop_response, attach_sources_to_conversation, apply_field_edit_proposal
1. Assumptionanswer_clarifying_questions, select_assumptions, select_hypothesis, get_assumption, get_hypothesis
2. Success criteriaselect_experiment, assign_experiment, list_eligible_experiment_assignees, approve_experiment, get_experiment, list_experiments
3. Experimentconfigure_data_tracker, get_data_tracker, list_data_tracker_rows, add_data_tracker_rows, update_data_tracker_row, preview_data_tracker_import, import_data_tracker_rows, get_data_tracker_import, complete_experiment
4. Decideget_learning, list_learnings, update_learning_draft, publish_learning, get_insight, prepare_decision_review, submit_decision, get_decision, list_decisions, list_evidence_assessments (history only)
Documentslist_documents, get_document, begin_document_upload, complete_document_upload, import_document, search_project_sources

Resources: swiftcns://projects/{projectId} (project context), .../experiments/{experimentId} (experiment brief), .../learnings/{learningId} (published Learning), .../decisions/{decisionId} (Decision Record).

Prompts: continue_experiment, import_experiment_evidence.

Workflow stages reported by get_conversation_progress: DISCOVERY, DRAFT, TRACKER, LEARNING (RUNNING only in edge cases).

Action Requests, in order: question_answer (any time), assumption_selection, hypothesis_selection, experiment_card_selection, assign_experiment, approve_experiment, setup_tracker, mark_complete, learning_card, and decision_record (separate slot). Learning results: MET, NOT_MET, UNCLEAR. Decision choices: MOVE_FORWARD, CHANGE_COURSE, TEST_AGAIN, DROP_IT.

Done when

  • Your agent can go from list_workspaces to submit_decision using only the tools above.

Troubleshooting

  • No tool drafts the Learning. Submit complete_experiment with continueConversation: true. If you didn't, call send_message with that action's actionRequestId and a returned parentMessageId.
  • Tracker set up, but no complete request. The stage waits on log_evidence; add rows first, then mark_complete appears.
  • setup_tracker has no proposed columns. Ask the user what one row is and propose columns; submit them with configure_data_tracker.
  • update_learning_draft conflicts. Read get_learning for the current version and test that value first.
  • Nothing offered after publish_learning. Call prepare_decision_review yourself.
  • Conflict on resubmit. Replay with the original identity and identical input; never a new key.
For agents: MCP tools and gotchas

Create IDs with generate_resource_id and reuse them on retry. create_conversation needs a title. Writes that take a requestKey (send_message, add_data_tracker_rows, imports) treat the same key as the same request. continueConversation: true on an action requests the next agent turn; it needs cns:read and cns:write.

Next

Troubleshooting and FAQ.

Evidence and the snapshot

Why SwiftCNS fixes the success criteria and the evidence at two moments, and why Not met and Unclear still count.

Troubleshooting and FAQ

Fixes for the problems people hit most, and short answers to common questions.

On this page

Before you startStepsWhat you getDone whenTroubleshootingNext