CourseProfiler MCP / ChatGPT App

CourseProfiler provides a Model Context Protocol endpoint for ChatGPT Apps and other MCP-capable clients. This is the preferred integration path for assistants that cannot freely browse and call arbitrary public APIs.

Endpoint

https://courseprofiler.com/mcp

Tools

create_race_plan — create a personalized race plan from course and runner inputs.
search_race_catalog — search CourseProfiler's race catalog and return CRSProf URLs.
import_course — import a fetchable official GPX/FIT/CRSProf URL, an official ZIP containing exactly one GPX, uploaded course source artifact, or inline/proxied content/base64 file object into CRSProf. ZIP files with multiple GPX tracks must be extracted and the intended GPX selected. Third-party route hosts such as Wikiloc may return 403 to server fetches.
enrich_course_waypoints — add structured aid stations, cutoffs, and canonical resources to a CRSProf artifact when they are missing.
generate_course_segments — generate analytical segments after waypoint enrichment, or from a catalog CRSProf that already includes official waypoint/resource data.
get_race_plan_requirements — ask what inputs are still needed for a complete race plan.
get_runner_profile_requirements — explain how users can obtain or generate a runner profile or evidence.
get_artifact_upload_requirements — explain the REST upload flow and accepted MCP inline file forms.
get_job — poll a CourseProfiler async job.
get_artifact — retrieve artifact metadata and a private short-lived download URL.

Waypoint/resource completeness

Catalog CRSProf files may already include official waypoints/resources/cutoffs. If they do, agents can use the catalog CRSProf URL directly for segmentation and race-plan creation. If official aid-station, water/food/crew, checkpoint, or cutoff data is missing, call enrich_course_waypoints with structured rows or ask the user for official aid/resource details before segmentation. If official pages and regulation PDFs disagree, or exact aid locations are not machine-readable, ask the user to confirm and include only confirmed aid stations.

Route-only plans are incomplete unless the user explicitly accepts missing aid/resource/cutoff details. If no waypoint data is available, ask the user whether a route-only plan is acceptable and label the resulting plan as missing aid/resource details. Resource values are canonical: use values such as water, drinks, food, fruit, hot_meal, crew, drop_bag, medic, toilet, or rest_area. Unsupported/free-text resource strings are ignored with warnings; preserve non-canonical details in waypoint notes/source text instead of inventing resource identifiers.

Course file fallback

If the catalog has no confirmed CRSProf and an official or third-party GPX/FIT/CRSProf URL cannot be fetched, is blocked, or returns 403, assistants must stop and ask the user to download the official route file and upload it through the artifact upload flow. Do not treat a blocked direct URL as permission to reconstruct the course. Do not create race plans from roadbooks, checkpoint tables, elevation profiles, aid-station lists, screenshots, or other synthetic/reconstructed route data; those are enrichment/context only and are not valid course geometry. Continue with the returned source_file artifact as course.source.kind=artifact.

Runner profile / evidence

Personalized plans require runner input. If the user does not already have a runner profile, call get_runner_profile_requirements and explain the options in user-facing terms: export a .usrprof from CourseProfiler, upload GPX/FIT activities as evidence, use public evidence URLs, or authenticate Strava in the browser and export/use the resulting profile.

One activity is usable but lower confidence; several recent, terrain-similar activities are recommended.
GPX/FIT evidence should include activity points with distance/elevation and preferably timestamps; HR/cadence are optional.
Uploaded .usrprof files complete as source_file artifacts and should be passed through runner.sources.
Do not invent runner fitness data. If no runner profile/evidence is available, ask the user for it before creating a personalized plan.

Hosted-client file uploads

MCP clients that can read local files may pass file bytes inline inside a file object as course_file.content or runner_profile_file.content for text formats such as GPX/XML/JSON/USRProf, or as course_file.base64 / runner_profile_file.base64 for binary formats such as FIT. Include name or file_name so CourseProfiler can infer the format.

Hosted MCP clients such as ChatGPT may not be able to pass local binary files directly to MCP tools. Bare local filesystem paths never work on the hosted MCP server; do not pass local paths or file:// URLs. If inline content/base64 is not available, call get_artifact_upload_requirements for instructions or upload local files through the public REST upload-to-artifact flow outside MCP: POST /api/artifact-uploads, PUT the bytes to the returned private upload URL while replaying all returned headers exactly, then complete with POST /api/artifact-uploads/{upload_id}/complete. Completion returns a source_file artifact ID. The helper is not a raw-byte MCP upload tool; MCP exposes instructions, not local file upload bytes. Hosted agents must use inline/proxied file objects or the REST upload flow.

For local GPX/FIT/CRSProf course files, use purpose course_source, then pass the returned artifact as course.source: { "kind": "artifact", "artifact_id": "art_..." } or to import_course.source.
For local .usrprof files, use purpose usrprof_source, then pass the returned source artifact via runner.sources, not usrprof_artifact_id.
usrprof_artifact_id is only for an already-converted USRProf artifact of type usrprof.
For local GPX/FIT/CRSProf runner evidence, use purpose runner_evidence and pass the returned artifact via runner.sources.

Option schemas

generate_course_segments.options accepts only segmentation options such as algorithm, flat_grade, slope_change_threshold, flat_max_delta, minimum_distance, flexible_minimum_distance, flexible_flat_max_delta, instant_mode, and include_routes. estimate.options accepts only strategy, gap_algorithm, and flat_grade. Put race metadata, start times, and waypoint/cutoff data in the course/waypoint fields, not in generic options.

Examples

Inline GPX course file plus inline USRProf file:

{
  "course_file": {
    "name": "course.gpx",
    "content_type": "application/gpx+xml",
    "content": "<gpx>...</gpx>"
  },
  "runner_profile_file": {
    "name": "runner.usrprof",
    "content_type": "application/vnd.courseprof.usrprof+json",
    "content": "{...}"
  },
  "pdf": { "enabled": true }
}

Uploaded CRSProf/course source artifact:

{
  "course": {
    "source": { "kind": "artifact", "artifact_id": "art_uploaded_course_source" },
    "segments": { "mode": "generate" }
  },
  "runner": {
    "sources": [{ "kind": "artifact", "artifact_id": "art_uploaded_usrprof_source" }]
  },
  "pdf": { "enabled": true }
}

Already-converted USRProf artifact:

{
  "course": { "crsprof_artifact_id": "art_course" },
  "runner": { "usrprof_artifact_id": "art_converted_usrprof" },
  "pdf": { "enabled": true }
}

Testing

In ChatGPT, enable Developer mode for Apps/Connectors if available, then create a connector pointing to https://courseprofiler.com/mcp. Availability and review requirements are controlled by the assistant platform.