List Tools

​

Overview

The tools/list method returns all tools available to the authenticated user. Tools are dynamically filtered based on OAuth authentication and database permissions, ensuring users only see tools they can execute.

​

Prerequisites

1. Session Initialization: Complete initialize → notifications/initialized flow
2. Authentication: Valid OAuth token or PAT with mcp.read scope
3. Session ID: Include Mcp-Session-Id header from initialization

​

Request Format

{
  "jsonrpc": "2.0",
  "id": "tools-list-123",
  "method": "tools/list",
  "params": {
    "cursor": "optional_pagination_cursor"
  }
}

​

Request Parameters

​

Response Format

​

Example Responses

{
  "jsonrpc": "2.0",
  "id": "tools-list-123",
  "result": {
    "tools": [
      {
        "name": "get_contacts",
        "description": "Retrieve contacts from Pipedrive CRM",
        "inputSchema": {
          "type": "object",
          "properties": {
            "limit": {
              "type": "integer",
              "description": "Maximum number of contacts to return",
              "minimum": 1,
              "maximum": 100
            },
            "filter": {
              "type": "string",
              "description": "Filter contacts by name or email"
            }
          },
          "required": ["limit"]
        }
      },
      {
        "name": "create_deal",
        "description": "Create a new deal in Pipedrive",
        "inputSchema": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Deal title"
            },
            "value": {
              "type": "number",
              "description": "Deal value"
            },
            "person_id": {
              "type": "integer",
              "description": "Associated person ID"
            }
          },
          "required": ["title", "value"]
        }
      }
    ],
    "nextCursor": null
  }
}

​

OAuth Filtering Behavior

Our implementation applies OAuth-based filtering:

​

User-Specific Tool Access

• Database Permissions: Tools filtered based on user’s database permissions
• OAuth Client ID: Each client gets appropriate tool subset
• Consistent Results: Same user always gets same tools (unless permissions change)
• Dynamic Loading: Tools loaded from database per user context

​

Access Control Validation

// Tools are filtered based on:
// 1. User's OAuth token client_id
// 2. Database tool permissions
// 3. Tool availability status
// 4. Server configuration

​

Tool Count Expectations

• Minimum: Authenticated users get at least some tools
• Maximum: Limited by user permissions and server configuration
• Consistency: Tool count remains stable across requests for same user

​

Implementation Notes

​

Request ID Requirements

• Must be unique within session
• Cannot be null (enforced by our implementation)
• String or number format accepted

​

Session Management

• Mcp-Session-Id header required after initialization
• Session validates OAuth token and permissions
• Invalid session returns authentication error

​

Pagination Support

• Uses cursor-based pagination
• nextCursor provided when more results available
• Empty cursor parameter returns first page

​

Error Handling

• -32000: Authentication/session errors
• -32600: Invalid request format
• -32602: Invalid parameters

​

Performance Considerations

• Tools cached per user session
• Database queries optimized for user permissions
• Results paginated for large tool sets

This endpoint provides the foundation for tool discovery, enabling clients to understand what operations are available before calling tools/call.