MCP guide

MCP (Model Context Protocol) lets an AI app such as Claude or ChatGPT use Venue Manager for you: look up free slots, book a court, assign a locker, mark attendance, collect a fee or send a payment link, all from a chat. You make an MCP server in Venue Manager, choose its tools, and paste its private address into the app. Each person who connects signs in with their own Venue Manager login, so the app can only do what that person's role allows.

Before you start

• Plan. MCP is included from the Professional plan, product by product (Slots or Classes). On Standard, servers cannot be made and connected apps stop working until you upgrade; nothing is deleted.
• Who sets it up. Someone whose role can manage the organisation's settings creates the server. Anyone with a login in your organisation can then connect, unless you limit the server to certain roles.
• The AI app. It must support remote MCP servers with OAuth sign-in. Most current apps do; the sections below show where to paste the address in each.

Create an MCP server

1. In Venue Manager open Settings › Developers › MCP servers and choose + New MCP server.
2. Give it a Server name people will recognise in their AI app, for example “Front desk”, and an optional one-line description.
3. Turn on the tools this team needs. Tools marked Changes data can create or change records; leave them off for a read-only server.
4. Under Who can connect, keep Any role that can use the tools or pick the roles allowed to connect.
5. Choose Create server. The server page shows its URL, which ends in a long random token. Copy it with the copy button.

Make one server per team or purpose, each with only the tools it needs: a front-desk server for bookings and lockers, a coaches' server for attendance, and so on. You can change a server's tools or name at any time and the URL stays the same.

Treat the URL like a key to a door: it is not enough on its own, because everyone still has to sign in, but share it only with your team. If it leaks, use Regenerate URL; the old address stops working at once and every connected app is signed out.

Things to ask

Once connected, ask in plain words. The app picks the tools, asks you for anything missing and, for tools that change data, most apps ask you to confirm first.

• “Which courts are free tomorrow between 5 and 8 pm?”
• “Book Cricket Nets 01 from 5 to 6 pm today for Muthaiah, +91 9663330207.”
• “Assign a free locker to this member for three months and record the payment.”
• “Mark attendance for today's evening batch: everyone present except Arun.”
• “Which orders are still unpaid this week? Send a payment link for the largest one.”

Claude (web)

1. On claude.ai open Settings › Connectors and choose Add custom connector.
2. Name it (for example “Venue Manager”), paste your server URL and choose Add.
3. Choose Connect. A Venue Manager window opens: sign in with your login, check what the app may do and choose Allow access.
4. In a chat, turn the connector on from the tools menu under the message box, then ask.

On Claude Team and Enterprise, an owner first adds the connector in the organisation's connector settings; each member then connects and signs in for themselves. Custom connectors depend on your Claude plan.

Claude Desktop

Claude Desktop shares connectors with your Claude account: add the server on claude.ai as above, or in the desktop app under Settings › Connectors › Add custom connector. Sign-in opens in your browser and returns to the app. There is no config file to edit for a remote server.

Claude Code

Add the server from your terminal, then sign in from inside Claude Code:

claude mcp add --transport http venue-manager https://www.sporfy.com/vm/mcp/<your-server-token>

# then, inside Claude Code
/mcp   # choose venue-manager › Authenticate

Add --scope user to use it in every project, or --scope project to share it through the project's .mcp.json. A shared file holds only the address; each person still signs in with their own login.

ChatGPT

1. In ChatGPT open Settings › Apps & Connectors. Under Advanced settings, turn on Developer mode if your plan asks for it.
2. Choose Create, give it a name and description, and paste your server URL as the MCP server URL.
3. Set Authentication to OAuth, confirm you trust the app, and choose Create.
4. Sign in to Venue Manager in the window that opens and choose Allow access.
5. In a chat, pick the connector from the + menu and ask.

Custom connectors depend on your ChatGPT plan, and on Business and Enterprise a workspace admin may need to allow them first.

Cursor

Add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "venue-manager": {
      "url": "https://www.sporfy.com/vm/mcp/<your-server-token>"
    }
  }
}

Open Cursor Settings › MCP; the server shows Needs login. Choose it, sign in to Venue Manager in the browser and allow access.

VS Code

With GitHub Copilot in agent mode, add the server to .vscode/mcp.json, or run MCP: Add Server from the command palette and choose HTTP:

{
  "servers": {
    "venue-manager": {
      "type": "http",
      "url": "https://www.sporfy.com/vm/mcp/<your-server-token>"
    }
  }
}

Choose Start above the server entry. VS Code asks to sign in; allow access in the browser and the tools appear in the chat's tool picker.

Windsurf

Open Cascade › MCP servers › Manage › View raw config and add the server to mcp_config.json:

{
  "mcpServers": {
    "venue-manager": {
      "serverUrl": "https://www.sporfy.com/vm/mcp/<your-server-token>"
    }
  }
}

Refresh the server list and sign in when asked.

Gemini CLI

Add the server to ~/.gemini/settings.json, then run /mcp auth venue-manager inside the CLI to sign in:

{
  "mcpServers": {
    "venue-manager": {
      "httpUrl": "https://www.sporfy.com/vm/mcp/<your-server-token>"
    }
  }
}

Other apps

Any app that supports remote MCP servers works the same way. Look for Connectors, Integrations or MCP servers in its settings, add a server of type HTTP or Streamable HTTP (not SSE), paste the URL, and choose OAuth if it asks how to sign in. Leave client ID and secret empty: the app registers itself. Automation tools that can only send a fixed header cannot use the MCP server, because every call needs a person's sign-in; use the REST API with an API key for server-to-server work instead.

Apps without remote servers

Some apps can only start local MCP servers. Bridge them with mcp-remote, an open-source helper that runs on your computer, opens the sign-in in your browser and forwards calls to the remote server (needs Node.js):

{
  "mcpServers": {
    "venue-manager": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.sporfy.com/vm/mcp/<your-server-token>"]
    }
  }
}

How sign-in works

Nobody types a key or secret into the AI app. When the app first calls the server it is told to sign in, finds our sign-in service by itself, registers, and opens a Venue Manager page in the browser. The person signs in with their own login and sees the organisation, their role and a plain list of what the app will be able to see and change. On Allow access the app receives tokens bound to that one server and that one organisation.

• The login must belong to the organisation that owns the server, with a role allowed by Who can connect.
• Sign-in is refused when the plan does not include MCP, or when the role cannot use any of the server's tools.
• Tokens from one server never work on another server, another organisation or any other Sporfy API.

What an app can do

On every call, the app may use a tool only when all of these hold. They are checked fresh each time, so a change takes effect on the next call:

• the tool is turned on for the server;
• the signed-in person's role allows it (coaches limited to their own classes see only those classes);
• the product is on Professional or above;
• the server is switched on and the person's access has not been revoked.

Tools tell the app whether they only read or change data, so apps can ask before changing anything. No tool deletes records or changes how a product is set up; that stays in Venue Manager.

Tokens and lifetimes

Apps refresh by themselves, so people stay connected while they keep using it. Codes and tokens are stored only as hashes.

Manage connected apps

On each server's page in Settings › Developers › MCP servers:

• Connected apps lists every person and app signed in, with when it was last used. Revoke signs one out at once.
• Regenerate URL replaces the address and signs everyone out; they reconnect with the new URL.
• Switching the server off or deleting it stops every connected app.
• Settings › Developers › Usage shows each call: who, which tool, and the result.

1. Discover

This part is for developers writing their own MCP client; apps above do all of it for you. The flow follows the MCP authorization spec: OAuth 2.1, protected resource metadata (RFC 9728), authorization server metadata (RFC 8414), dynamic client registration (RFC 7591) and resource indicators (RFC 8707). A call without a token answers 401 with where to start:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Venue Manager", resource_metadata="https://www.sporfy.com/vm/mcp/<your-server-token>/.well-known/oauth-protected-resource"

GET https://www.sporfy.com/vm/mcp/<your-server-token>/.well-known/oauth-protected-resource

{
  "resource": "https://www.sporfy.com/vm/mcp/<your-server-token>",
  "authorization_servers": ["https://www.sporfy.com/vm/oauth"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

2. Register the app

Register once per app. Clients are public (no client secret) and must use PKCE. Give 1 to 5 redirect URIs: https, an http://localhost or http://127.0.0.1 address, or your app's own scheme.

curl -X POST https://www.sporfy.com/vm/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My venue assistant", "redirect_uris": ["https://app.example.com/oauth/callback"]}'

# 201 Created
{
  "client_id": "mcpc_…",
  "client_name": "My venue assistant",
  "redirect_uris": ["https://app.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

3. Ask the person

Make a random code_verifier, send its SHA-256 as code_challenge, and open the authorization page in the person's browser. The resource is the server URL. After Allow access the browser returns to your redirect URI with code and your state.

https://www.sporfy.com/vm/connect-app
  ?response_type=code
  &client_id=mcpc_…
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &code_challenge=<base64url(sha256(code_verifier))>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fwww.sporfy.com%2Fvm%2Fmcp%2F<your-server-token>
  &scope=mcp
  &state=<random>

4. Get tokens

curl -X POST https://www.sporfy.com/vm/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=mcpc_… \
  -d code=vmac_… \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier=<code_verifier>

{
  "access_token": "vmat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "vmrt_…",
  "scope": "mcp"
}

5. Call tools

Send JSON-RPC 2.0 messages with POST to the server URL. Start with initialize, then list and call tools.

curl -X POST https://www.sporfy.com/vm/mcp/<your-server-token> \
  -H "Authorization: Bearer vmat_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "my-app", "version": "1.0"}}}'

{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18", "capabilities": {"tools": {"listChanged": false}}, "serverInfo": {"name": "Front desk", "version": "1.0.0"}, "instructions": "Tools for running a venue: …"}}

6. Refresh and revoke

# a new pair; the old refresh token stops working
curl -X POST https://www.sporfy.com/vm/oauth/token \
  -d grant_type=refresh_token -d client_id=mcpc_… -d refresh_token=vmrt_…

# sign out: revoking a refresh token ends the whole sign-in
curl -X POST https://www.sporfy.com/vm/oauth/revoke -d token=vmrt_…

Transport and versions

• Streamable HTTP: POST to the server URL; answers are plain JSON. The server never pushes messages, so GET answers 405.
• Batches (a JSON array) are accepted. Notifications get 202 with no body.
• Protocol versions: 2025-06-18, 2025-03-26 and 2024-11-05. Ask for one in initialize; an unknown version gets the newest.
• https only. Every answer carries X-Request-Id; quote it when you contact us.

Methods

Tools

MCP tools and REST endpoints are the same operations: bookings, holds, blocks, payments, lockers, rentals, memberships, games, classes, students, fees, attendance and customers. The API reference lists each one with its arguments, and names its MCP tool (for example slots.book). A server offers only the tools you turned on, narrowed further by each person's role.

Errors

Sign-in errors use the standard OAuth codes: invalid_request, invalid_client, invalid_grant, access_denied and invalid_redirect_uri.

Rate limits

MCP calls share your organisation's API limits: 60 a minute and 5,000 a day on Professional, 120 and 15,000 on Premium, and more on Enterprise; see plans and rate limits. Past a limit, the tool result is an error with rate_limited and the time to wait.

Troubleshooting