← Back to Docs

MCP Quickstart

Developer

MCP Quickstart

Priiism exposes a network-reachable Model Context Protocol (MCP) endpoint so you can connect an MCP-compatible AI client — such as Cursor and other tools that speak MCP — directly to your project. The client can then list and call your project’s tools (deploys, environment variables, source control, database, and more) using your own API key.

This walkthrough gets you from zero to a successful tool call in a few minutes.

1. Create a key

Open Account Settings → Developer and create a key (see Authentication). For a single project, a project-scoped key is simplest — the project is then implied and you don’t have to name it on every call. Copy the vk_live_... secret when it is shown; it is revealed only once.

Give the key scopes matching what you want the client to do. For a read-only exploration start, any valid key can already list and call the read-only tools.

2. The endpoint

The MCP endpoint is served on the same origin as your dashboard:

POST https://YOUR-APP-HOST/api/mcp/v1

It implements the MCP streamable-HTTP transport:

  • POST carries JSON-RPC 2.0 messages (initialize, tools/list, tools/call).
  • GET opens a server-to-client event stream. Today the server sends no unsolicited notifications, so the stream simply connects and stays quiet.

Authentication is the same Bearer header used everywhere else:

Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Configure a client

Most MCP clients accept a JSON configuration block describing each server. Point a streamable-http (or “http”) server entry at the endpoint and pass your key as an Authorization header:

{
  "mcpServers": {
    "priiism": {
      "type": "streamable-http",
      "url": "https://YOUR-APP-HOST/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Replace YOUR-APP-HOST with your dashboard host and the placeholder with your real key. Field names vary slightly between clients (some call it servers, some transport instead of type), but every MCP client needs the same three things: the transport, the URL, and the Authorization header.

4. List the available tools

You can exercise the endpoint directly with curl. First, list the tools your key is allowed to use — the server filters this list by your key’s scopes, so you only ever see what you can actually call:

curl -X POST https://YOUR-APP-HOST/api/mcp/v1 \
  -H "Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response is a JSON-RPC result whose tools array lists each tool’s name, description, and inputSchema:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "project_info",
        "description": "Get project metadata and configuration",
        "inputSchema": { "type": "object", "properties": {} }
      }
    ]
  }
}

5. Call a read-only tool

Now call a safe, read-only tool. project_info returns your project’s metadata and is a good first call:

curl -X POST https://YOUR-APP-HOST/api/mcp/v1 \
  -H "Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": { "name": "project_info", "arguments": {} }
      }'

If your key is org-wide rather than project-scoped, add the target project to the tool’s arguments:

{ "name": "project_info", "arguments": { "project": "YOUR-PROJECT-ID" } }

A successful call returns a JSON-RPC result with the tool’s content. See AI Agent Tools for the full catalog of tools you can call.

What can go wrong

  • 401 unauthorized — the Authorization header is missing or the key is invalid, revoked, or expired. Re-check the key; see API Reference → Errors.
  • Tool call returns an error result — the tool is not permitted by your key’s scopes, or (for an org-wide key) you didn’t pass a project argument. Widen the key’s scopes or name the project.
  • A file-editing tool reports it isn’t available remotely yet — a small set of tools that read or write the sandbox working directory are listed but not yet callable over the remote transport. Everything else works today.

Next steps