MCP for AI Agents

Plugsurfing exposes a public MCP endpoint at:

https://developer.plugsurfing.com/mcp

Use it when your AI client supports remote MCP servers over HTTP and you want a live tool layer on top of the public Drive API contract.

For the broader AI-assisted workflow, start with the AI Integration Playbook.

Why use MCP if OpenAPI already exists?

OpenAPI remains the source of truth for the Drive API contract.

MCP is useful when your AI client can call tools and you want to stay inside the same AI workflow to:

search endpoints from a task description instead of scanning the full contract manually
inspect one endpoint at a time with get-endpoint
execute a request directly from the AI client once secrets are configured safely

If you only need the contract or code generation, openapi.json is usually enough on its own.

What the MCP server exposes today

The current MCP server is tools-only.

Today it exposes tool categories for:

endpoint discovery, such as list-endpoints, search-endpoints, and get-endpoint
environment inspection with get-server-variables
request execution with execute-request

The tools listed above reflect the current surface. Always verify capabilities via the live capability handshake, as the server may evolve.

Do not assume the server exposes MCP resources, prompts, or domain-specific business workflows unless you have verified that directly in the live capability output.

When to use MCP vs OpenAPI vs the docs

Use each surface for a different job:

use the Drive API docs on https://developer.plugsurfing.com to discover the right guides and reference pages
use https://developer.plugsurfing.com/openapi/openapi.json as the source of truth for the public contract
use https://developer.plugsurfing.com/mcp when you want a tool-driven way to discover endpoints, inspect endpoint details, and execute requests interactively

The strongest workflow is to use all three together instead of treating any single surface as complete on its own.

Base URLs and authentication

When you use MCP-driven requests, use these Drive API base URLs:

Stage: https://drive-api-stage.plugsurfing.com/drive
Production: https://drive-api.plugsurfing.com/drive

At the moment, get-server-variables advertises drive-api-stage. Production also exists, so choose the base URL explicitly.

Real Drive API calls still authenticate with:

X-API-Key

execute-request can send real Drive API calls. Your AI client must inject X-API-Key securely. Keep API keys in secure tool configuration or in your backend environment. Never paste them into chat prompts or client-side code.

If you want to compare MCP behavior with a direct HTTP call, start with this minimal stage request:

curl --request POST \
  --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=59.33&longitude=18.07&distance=5000' \
  --header "X-API-Key: $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'

Practical MCP tasks

These are the best uses of the current MCP server:

Discover an endpoint from intent

Ask your client to search for a task such as geosearch, session receipt retrieval, or charging key activation. Then use get-endpoint to inspect the exact method and path.

Inspect endpoint details

Use get-endpoint to inspect the method, path, and endpoint-level details, then verify request and response payloads in the public OpenAPI document at https://developer.plugsurfing.com/openapi/openapi.json.

Inspect server variables

Use get-server-variables to inspect the currently advertised server variables before constructing requests. Treat the Drive API base hosts documented below as the correct environment references.

Execute a stage request

Use execute-request only when your client can pass secrets safely. Prefer stage first, verify the request body and headers, and then inspect the returned payload before integrating the call into your codebase.

Safety and limitations

Keep these limits in mind:

MCP helps with discovery and inspection, but it does not replace the workflow guides.
Some operational behavior lives only in the guides, especially for webhooks, retries, payment flows, and session lifecycle edge cases.
Search quality depends on the terms you use. If a search is too broad or too conversational, switch to exact endpoint names or product terms from the docs.
The public MCP surface does not currently expose dedicated schema-inspection or code-snippet tools, so use the public OpenAPI document when you need full request and response details.

When in doubt, verify behavior in: