List Prompts

​

Overview

The prompts/list method returns all prompt templates available to the authenticated user. Prompts are user-controlled templates that provide structured messages and instructions for language model interactions.

​

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": "prompts-list-123",
  "method": "prompts/list",
  "params": {
    "cursor": "optional_pagination_cursor"
  }
}

​

Request Parameters

​

Response Format

​

Example Responses

{
  "jsonrpc": "2.0",
  "id": "prompts-list-123",
  "result": {
    "prompts": [
      {
        "name": "deal_analysis",
        "description": "Analyze deal progress and provide recommendations",
        "arguments": [
          {
            "name": "context_type",
            "description": "Type of analysis context (deal, contact, activity)",
            "required": true
          },
          {
            "name": "context_id",
            "description": "ID of the specific item to analyze",
            "required": true
          }
        ]
      },
      {
        "name": "sales_summary",
        "description": "Generate sales performance summary for a person",
        "arguments": [
          {
            "name": "person_id",
            "description": "ID of the person to analyze",
            "required": true
          },
          {
            "name": "time_period",
            "description": "Analysis time period (month, quarter, year)",
            "required": false
          }
        ]
      },
      {
        "name": "contact_insights",
        "description": "Generate insights about a contact's interaction history"
      }
    ],
    "nextCursor": null
  }
}

​

Prompt Arguments

​

Argument Types

Prompt arguments define customization parameters:

• Required Arguments: Must be provided in prompts/get calls
• Optional Arguments: Can be omitted, may have default values
• Context Arguments: Often reference IDs from your CRM/system

​

Common Argument Patterns

​

Argument Validation

Arguments are validated when used in prompts/get:

// Example argument validation
const args = {
  context_type: "deal", // Required: must be provided
  context_id: "123", // Required: must be provided
  time_period: "month", // Optional: can be omitted
};

​

OAuth Filtering Behavior

Our implementation applies OAuth-based filtering:

​

User-Specific Prompt Access

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

​

Access Control Validation

// Prompts are filtered based on:
// 1. User's OAuth token client_id
// 2. Database prompt permissions
// 3. Prompt availability status
// 4. Server configuration

​

Prompt Count Expectations

• Minimum: Authenticated users get at least some prompts
• Maximum: Limited by user permissions and server configuration
• Consistency: Prompt 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

• Prompts cached per user session
• Database queries optimized for user permissions
• Results paginated for large prompt sets

​

Prompt Template Structure

• Each prompt has unique name identifier
• Optional arguments define customization parameters
• Arguments have required/optional flags
• Descriptions help users understand prompt purpose

This endpoint enables prompt discovery, allowing clients to understand what template-based interactions are available before calling prompts/get.