MCP server

The Mountaya MCP server exposes the read-only Data API to AI agents over the Model Context Protocol, served as MCP Streamable HTTP at the host root. The public endpoint is https://mcp.mountaya.com/ (the bare host root, with a trailing slash). Point any MCP client at it and the agent gains read-only tools for outdoor routing, places, and geometry analysis, plus a resource that serves the full Data API schema. No tool creates, updates, or deletes anything.

There are two ways to authenticate, on the same endpoint:

• An interactive assistant connects over OAuth. Claude, ChatGPT, and other MCP-compatible assistants connect through a sign-in screen, with no keys in a config file. See Connect your assistant (OAuth).
• A non-interactive client sends an API key pair. A client you configure yourself sends a publishable and secret key pair on every request, and the server brokers session tokens for it. See Connect a non-interactive client (key pair).

Same endpoint, same tools.

What you can do

The server exposes the read-only Data API operations as tools. Grouped by what they do:

Coordinates are [longitude, latitude] in WGS 84, distances are in meters, and durations are in seconds, the same conventions as the Data API. For the exact parameters of each tool, see Tools below.

Connect your assistant (OAuth)

Use this path for an interactive assistant like Claude or ChatGPT: you connect once through a sign-in screen, with no app to register and no keys to paste into a config file. The connector URL is the bare MCP host root, https://mcp.mountaya.com/, with a trailing slash and no path after it. The assistant discovers the protocol and the OAuth server from it.

Connect once

Connecting is a one-time browser flow. After it, the assistant holds a token and calls the tools on its own; you do not sign in again per request.

How access is scoped

The assistant acts with the publishable key you chose on the consent screen, and nothing wider.

• One organization. A publishable key belongs to one organization, so the assistant can read only that organization's data. To let an assistant work with a different organization, connect again and pick a key in that organization.
• Metered to that organization. Calls the assistant makes count against the chosen key's organization under the same rate limits as any other Data API call.
• No secret key, ever. The flow binds a publishable key, by id, never its raw value and never a secret key. The assistant cannot see or use your secret key, and the consent screen never exposes one.
• Read-only. Every tool is a read; nothing in the tool set creates, updates, or deletes your data.

For the full model, see OAuth for MCP connectors in the authentication guide.

Set up your assistant

The connect flow is the same everywhere: paste the connector URL, sign in, pick a key, authorize. Each assistant just exposes that field in a slightly different place, and a few have quirks worth knowing.

Connect a non-interactive client (key pair)

Prefer this path for a non-interactive client you configure yourself: a local agent, a CLI, or a server-side runtime that authenticates without a person signing in. The client sends a publishable key in X-API-Key and a secret key in X-Secret-Key on every request. The server validates the pair, mints (or reuses a cached) Data API session token on your behalf, and proxies the operation, so your client never calls the session endpoint itself. A missing or malformed key pair is rejected at the edge with 401 Unauthorized.

Add the server to your client with the public endpoint and your key pair. Keep the two keys as placeholders below and replace them with your own. Create keys in your Mountaya app, by opening your organization and its API keys tab, and enable the mcp scope. It is the scope the connector needs; data authorizes querying the Data API directly and is a separate product.

claude mcp add mountaya \
  --transport http \
  --header "X-API-Key: pk_your_publishable_key" \
  --header "X-Secret-Key: sk_your_secret_key" \
  https://mcp.mountaya.com/

The client sends both keys and the server does the rest:

See authentication for how the underlying key pair and session tokens work.

Tools

The server registers read-only tools, each proxying one Data API GraphQL query. Coordinates are [longitude, latitude] in WGS 84, distances are in meters, and durations are in seconds. A GraphQL-level failure is returned as a tool error carrying the Data API's {message, path, extensions} envelope, so the agent can read the error code and self-correct.

Routing

Places

Pair itinerary with terrainProfile or analyzeGeometry on a segment's geometry to answer questions about the ground a saved route actually covers.

Analysis

Every terrain result carries zoom and resolutionMeters, so a reading can be reproduced, and coveredCount alongside count. Points outside DEM coverage come back with a null elevation, slope, and aspect rather than a placeholder value — weight any average by coveredCount.

slope is in degrees and aspect is a downhill compass bearing (0-360, 0 = north). aspectOctant and steepnessBand use the same vocabulary as the aspect and steepness overlays, so a value you read here matches the legend a user sees on the map.

A terrainProfile sample carries its own distanceMeters along the line. Read it rather than multiplying the index by spacingMeters, which is a target in both directions: input vertices are always retained, so the interval across a bend is shorter, and a very long line is sampled coarser so one profile cannot return an unbounded number of points.

Prompts

The server exposes reusable procedures as MCP prompts. Each one names the tools to call and the order to call them in, so an assistant does not have to work out the sequence from tool descriptions alone. Clients that support the prompts primitive list them the way they list tools; how you invoke one depends on your client.

These are written for an external assistant and only use tools this server exposes. The co-pilot inside Mountaya Studio follows its own procedures, which additionally drive the map and the editor — capabilities that have no equivalent here.

Schema resource

The server also exposes the Data API schema as an MCP resource, so a client can fetch the full SDL the tools are generated from.

Limits

The MCP surface inherits the Data API's behavior.

• Read-only. Every tool is a query. There are no mutations.
• Rate limits. Calls count against the same rate limits as the Data API, keyed to your organization. See authentication for limits and the 429 response.
• Error parity. Tool errors carry the Data API's GraphQL error envelope verbatim, including each entry's code and path, so a failure surfaces the same machine-readable detail you would get calling the Data API directly.
• Terrain bounds. A grid is capped at 64 columns by 64 rows per call and sampled at a fixed DEM zoom. Narrow the bounding box rather than raising the resolution: past the DEM's own resolution a denser grid returns the same ground twice. Point queries take up to 100 locations at once, which is cheaper than the same count one at a time.

Troubleshooting

If an OAuth-connected assistant's Mountaya tools start failing, the connection's key or organization has changed out from under it. A connection is bound to the specific publishable key you chose, so it breaks when:

• the key was revoked or deleted,
• the key lost MCP access (its mcp scope was removed, or the organization's Outdoor Intelligence access was),
• the organization was deactivated, or
• you were removed from the organization.

The fix is to reconnect and choose another key. A token refresh alone keeps the old binding, so it will keep failing for the same reason; an explicit reconnect is what lets you bind a different, working key.

See also