MCP Endpoint

The Model Context Protocol (MCP) is an open standard that lets AI assistants discover and call tools at runtime. Aprovan exposes your workspace's granted tool set as an MCP server — point Claude Desktop, Cursor, or any MCP-compatible client at your workspace endpoint and the client will automatically discover what's available and prompt you to sign in.

Endpoint URL

Each workspace has its own MCP endpoint. Replace <workspaceId> with the ID of your workspace (visible on the Install tab of the workspace admin page).

MCP endpoint

https://gateway.aprovan.com/mcp/<workspaceId>

Meta-tools

The endpoint always exposes four meta-tools. These are what tools/list returns. Callers with per-tool grants see the same four names; the grants control which underlying providers they can actually reach via call_tool.

list_tools

Returns the caller's granted tools filtered by their permission set. Use this to discover which providers and operations are available to you.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_tools",
    "arguments": {}
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{"provider":"github",
  "operation":"repos.list"},
  {"provider":"stripe",
  "operation":"*"}]"
    }]
  }
}

search_tools

Full-text search over the caller's granted tools. Useful when the client needs to pick the right operation from a large permission set.

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "query": "create pull request"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{"provider":"github",
  "operation":
    "pulls.create",
  "summary":
    "Create a pull request"}]"
    }]
  }
}

tool_info

Returns the full schema (parameters, description) for a single provider operation.

Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tool_info",
    "arguments": {
      "provider": "github",
      "operation": "repos.get"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{
      "type": "text",
      "text": "{"provider":"github",
  "operation":"repos.get",
  "parameters":{
    "owner":{"type":
      "string"},
    "repo":{"type":
      "string"}}}"
    }]
  }
}

call_tool

Invokes a provider operation. The caller must have a grant for provider + operation (or a wildcard grant on the provider).

Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "call_tool",
    "arguments": {
      "provider": "github",
      "operation": "users.getByUsername",
      "args": {
        "username": "octocat"
      }
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{
      "type": "text",
      "text": "{"login":"octocat",
  "id":1,
  "name":
    "The Octocat", ...}"
    }]
  }
}

Auth flow

The endpoint is protected by Cognito bearer tokens. There are two ways to authenticate:

OAuth-aware client (Claude Desktop, Cursor)

The client fetches the OAuth Protected Resource Metadata document at: 

/.well-known/oauth-protected-resource
  /mcp/<workspaceId>

This document points to the Cognito authorization and token endpoints. The client initiates the auth-code flow automatically and prompts you to sign in via the Cognito hosted UI. After consent, the client stores the access token and uses it on every subsequent request.

Hand-configured client

Obtain a Cognito access token from your workspace admin and paste it into the client's bearer-token field. The token is passed as: 

Authorization: Bearer <access_token>

Cognito access tokens expire after one hour. Refresh tokens can be used to obtain new access tokens without re-prompting.

Per-caller filtering

tools/list always returns the four meta-tools ( list_tools, search_tools, tool_info, call_tool). However, when a caller invokes call_tool name=list_tools, the returned tool list is intersected with the caller's permission grants — callers only see what they are allowed to call. A workspace admin can view and manage grants on the Permissions page.

Troubleshooting

Error Likely cause & fix
401 Unauthorized Token is missing, expired, or malformed. Re-authenticate: disconnect the client, re-add the server, and sign in again.
403 Forbidden Your user is not a member of this workspace, or you lack a grant for the requested provider + operation. Contact a workspace admin.
Unknown tool The tool name is not one of the four meta-tools. Use search_tools to find the right provider and operation name.
insufficient_scope The Cognito token does not include the required OAuth scope. Re-authenticate after a workspace admin has granted you the correct scopes.