MCP Server for AI Motion Analysis

Quickstart

Use the hosted Streamable HTTP endpoint with a personal CheckMotion API key. The server validates your identity and exposes the complete tool set automatically.

1. Create a key

2. Add the server

3. Start a chat

Confirm that 15 tools are discovered, enable CheckMotion, and ask for a video analysis.

Hosted connection

MCP URL
https://api-v2.checkmotion.app/mcp

Authorization
Bearer cm_live_YOUR_API_KEY

Your key is shown once

Copy the complete cm_live_… value when it is created. Store it in the client's secret or bearer-token field—not in the server URL, prompts, screenshots, or source control.

Connect ChatGPT

ChatGPT connects to the hosted HTTPS endpoint. Availability and labels for custom MCP connections can depend on the account, workspace, and current ChatGPT interface.

01
Open the app or connector setup
Enable developer mode if your account or workspace requires it, then open the area for creating a custom app or MCP connection.
02
Enter the hosted server URL
Use https://api-v2.checkmotion.app/mcp.
03
Configure one authentication method
If the UI provides a bearer-token field, enter only cm_live_…. If it provides request headers, set Authorization to Bearer cm_live_…. Do not configure both.
04
Scan and test the tools
Confirm all 15 tools, enable the connection in a new chat, and begin with a focused prompt such as “Detect the sport and movement in this video.”

ChatGPT interfaces evolve

Look for custom apps, connectors, or developer-mode MCP connections if the labels differ. The required wire-level result remains an HTTPS MCP connection with the CheckMotion bearer token.See official ChatGPT app guidance.

Connect Codex

Codex can connect to the hosted CheckMotion service while keeping the API key out of its configuration file.

Terminal

export CHECKMOTION_API_KEY='cm_live_YOUR_API_KEY'

~/.codex/config.toml

[mcp_servers.checkmotion]
url = "https://api-v2.checkmotion.app/mcp"
bearer_token_env_var = "CHECKMOTION_API_KEY"

On macOS, apps opened from Finder may not inherit your shell environment. Set the variable with launchctl setenv CHECKMOTION_API_KEY 'cm_live_…', then fully quit and reopen Codex.

Tool catalog

Every authenticated API key sees the same 15 focused tools. The assistant composes them based on the requested analysis.

checkmotion_healthServiceCheck MCP and upstream API healthNone
checkmotion_prepare_video_uploadVideoReserve a signed local-video uploadFile name, type, size, optional SHA-256
checkmotion_create_keypoint_jobPoseCreate frame-level pose extractionVideo source
checkmotion_get_keypoint_jobPoseRead pose-job status and resultKeypoint job ID, result mode
checkmotion_get_job_videoVideoCreate owned video-access metadataKeypoint job ID
checkmotion_delete_keypoint_jobPoseDelete pose job and assetsJob ID, delete confirmation
checkmotion_create_sport_detection_jobAnalysisDetect sport and movementVideo source, language
checkmotion_create_detailed_metrics_jobAnalysisGenerate movement-specific metricsKeypoint job, activity
checkmotion_create_performance_rating_jobAnalysisRate the recorded performanceKeypoint job, activity, optional metrics
checkmotion_create_report_jobAnalysisCreate a coaching reportOne or more component job IDs
checkmotion_get_analysis_jobAnalysisRead primitive-analysis status and resultAnalysis job ID, result mode
checkmotion_delete_analysis_jobAnalysisDelete a primitive-analysis jobJob ID, delete confirmation
checkmotion_create_full_analysis_jobPipelineStart the complete analysis workflowUploaded video, language
checkmotion_get_full_analysis_jobPipelineRead full-analysis status and resultFull-analysis job ID, result mode
checkmotion_analysis_chatCoachingAsk a bounded, report-grounded questionAnalysis context, message

Deletion is explicit

Delete tools require both the job ID and the exact confirmation value delete.

Delete input

{
  "jobId": "11111111-1111-4111-8111-111111111111",
  "confirmation": "delete"
}

Video inputs

Remote HTTPS videos can be passed directly to keypoint and sport-detection tools. Local files use a short-lived upload slot because MCP JSON is not designed for large binary bodies.

Remote HTTPS video

Tool input

{
  "source": {
    "videoUrl": "https://example.com/recording.mp4"
  },
  "language": "en"
}

Local file: reserve, upload, consume

1
Reserve an upload
Call checkmotion_prepare_video_upload with the file metadata.
2
Upload the exact bytes
PUT the file to the returned uploadUrl using every returned required header.
3
Use the upload ID
Pass the returned uploadId to the video-accepting tool. A successful analysis consumes it once.

Prepare upload input

{
  "fileName": "rep.mp4",
  "contentType": "video/mp4",
  "contentLength": 12345678
}

Upload bytes

curl --request PUT "$UPLOAD_URL" \
  --header 'Content-Type: video/mp4' \
  --header "Content-Length: $(wc -c < rep.mp4 | tr -d ' ')" \
  --data-binary @rep.mp4

Analyze uploaded video

{
  "source": {
    "uploadId": "up_0123456789abcdef0123456789abcdef"
  },
  "language": "en"
}

Upload guarantees

Slots are signed, tenant-bound, size-checked, optionally SHA-256 checked, short-lived, and consumed once. Active upload count and total staged bytes are capped per API key.

Analysis workflows

Choose a single primitive when you need one artifact, compose the stages for more control, or run the full pipeline for a complete coaching result.

Keypoints only

Create a keypoint job from a remote URL or upload, then poll it. No sport detection, scoring, metrics, or report is started.

Composed analysis

Run pose and sport detection, then metrics, rating, and report in dependency order. Each stage remains independently addressable.

Full pipeline

Prepare a local upload, call the full-analysis tool with its upload ID, then poll the returned master job.

1
Capture evidence
Complete keypoints and, when needed, sport detection from the same video.
2
Generate metrics
Pass the owned keypoint job and resolved activity into detailed metrics.
3
Rate performance
Use the keypoints, activity, and optional metrics job to calculate the performance rating.
4
Create the report
Provide any valid non-empty combination of owned component jobs, then use analysis chat for bounded follow-up questions.

Safe retries with your own job ID

Create tools accept an optional canonical lowercase UUID. Reusing the same ID with the same request is idempotent; reusing it for a different operation or payload returns JOB_ID_CONFLICT.

Results & resources

Large pose and analysis payloads can stay outside the conversation context while remaining available through protected MCP resources.

summary · default

Returns job status plus links to full resources, keeping the conversation compact.

inline

Returns the exact API result when it fits the configured inline-size limit.

resource

Always returns a protected MCP resource link instead of embedding the result.

Job lifecycle

PENDING

Accepted and waiting for processing capacity.

PROCESSING

The requested analysis is currently running.

COMPLETED

The result or protected resource is ready.

FAILED

The job ended with a structured error.

checkmotion://keypoint-jobs/{jobId}/resultComplete keypoint result
checkmotion://keypoint-jobs/{jobId}/frames/{cursor}/{limit}Keypoint frames, paged up to 250 at a time
checkmotion://keypoint-jobs/{jobId}/videoShort-lived owned video-access metadata
checkmotion://analysis-jobs/{jobId}/resultPrimitive analysis result
checkmotion://full-analyses/{jobId}/resultComplete full-analysis result

Authentication & security

The MCP service is an authenticated adapter and ownership boundary. It does not operate a shared credential pool or duplicate the analysis engine.

Per-user authentication

The same personal API key validates the MCP request and authorizes the corresponding CheckMotion API call.

Tenant isolation

Every job, upload, resource, video read, composition, and delete operation checks ownership.

No plaintext key storage

Raw API keys are not stored in the MCP database or written to application logs.

Short-lived access

Signed upload and video links expire. Video credentials use authenticated encryption, never plaintext URL parameters.

Key validation does not consume analysis quota. Normal API operations retain their usual accounting. Deleted, invalid, and exhausted keys are rejected; revoking a key also stops its signed video-access links from reaching the API.

Errors & recovery

Connection failures use HTTP status codes before MCP dispatch. Tool failures return a stable machine-readable category and retry guidance.

401 Unauthorized

Missing, malformed, deleted, or invalid CheckMotion API key.

403 Forbidden

Rejected host or origin, or insufficient client access policy.

429 Too Many Requests

The CheckMotion API key has exhausted its current call quota.

503 Unavailable

Key validation or the upstream CheckMotion API is temporarily unavailable.

Tool error

{
  "error": "Human-readable message",
  "error_type": "STABLE_ERROR_CODE",
  "error_details": null,
  "retryable": false
}

JOB_NOT_FOUND: Missing, unowned, or wrong-type job
JOB_ID_CONFLICT: Job ID reused for a different request
INVALID_JOB_ID: ID is not a canonical lowercase UUID
UPLOAD_NOT_FOUND: Upload is missing, consumed, or belongs to another key
UPLOAD_EXPIRED: The signed upload slot has expired
UPLOAD_LIMIT_EXCEEDED: Per-key staging limits were reached
UPLOAD_DIGEST_MISMATCH: Uploaded bytes do not match the reserved digest
UPSTREAM_TIMEOUT: The CheckMotion API exceeded its timeout
UPSTREAM_UNAVAILABLE: The CheckMotion API could not be reached

Troubleshooting

Most connection problems come from authentication configuration, expired uploads, upstream availability, or stale client tool discovery.

Authentication failed

Verify the key starts with cm_live_. Use either the bearer-token field or the Authorization header—not both—and confirm the key is active with remaining calls.

Client cannot reach the server

Confirm the server URL is exactly https://api-v2.checkmotion.app/mcp, then refresh or rescan the connection.

Upload failed

Match the reserved content type and exact byte length, check the expiration time and staging limits, and do not reuse a consumed upload ID.

Job or resource not found

Confirm the job ID is lowercase canonical UUID syntax and belongs to the same API key and expected job type.

Manage API keys Read the API reference Contact support

Motion intelligence, one prompt away.

Connect, analyze, and inspect every result.