PRSNA MCP Server

A Model Context Protocol (MCP) server that enables AI tools (Claude, Cursor, OpenAI) to access personality profiles and communication insights from the PRSNA platform.

🚀 Quick Start

For most users:

npm install -g @prsna_ai/mcp-server

Then follow our 📋 Complete Setup Guide for step-by-step instructions!

Features

• Authentication: Secure connection to PRSNA API with bearer token
• Profile Management: List, search, and retrieve personality profiles
• Communication Intelligence: Get personalized communication tips and strategies
• Quick Lookup: @mention functionality for fast profile context
• Caching: Intelligent caching for improved performance
• Error Handling: Robust error handling with detailed logging

Available Tools

| Tool | Description | |------|-------------| | prsna_login | Authenticate with PRSNA using bearer token | | list_personality_profiles | List all saved personality profiles | | search_personality_profiles | Search profiles by name, company, or job title | | get_personality_context | Get comprehensive personality context for a person | | get_communication_tips | Get specific communication tips for interacting with someone | | mention_person | Quick lookup for @mention functionality | | my_personality_profile | Get your own personality profile and assessment results |

Installation

Prerequisites

• Node.js 16+
• PRSNA account with saved personality profiles
• PRSNA MCP API token (generated from your PRSNA profile settings)

Setup

1. Clone and Install

   cd prsna-mcp
   npm install

2. Get Your PRSNA MCP Token

   • Log into PRSNA and go to Profile Settings
   • Click on the "MCP Tokens" tab
   • Generate a new token with a descriptive name (e.g., "Claude Desktop")
   • Copy the token immediately (it won't be shown again)

3. Environment Configuration

   cp env.example .env

   Edit .env file:

   # Required: Your PRSNA MCP token (starts with prsna_)
   PRSNA_API_TOKEN=prsna_your_generated_token_here
      
   # Optional: Custom API URL (defaults to production)
   PRSNA_API_URL=https://prsna.ai/api
      
   # Optional: Logging level
   LOG_LEVEL=info

4. Build the Project

   npm run build

5. Test the Server

   npm test

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "prsna": {
      "command": "node",
      "args": ["/absolute/path/to/prsna-mcp/dist/index.js"],
      "env": {
        "PRSNA_API_TOKEN": "prsna_your_generated_token_here"
      }
    }
  }
}

Cursor IDE

Add to your Cursor settings (.cursor-settings/mcp.json):

{
  "mcp": {
    "servers": {
      "prsna": {
        "command": ["node", "/absolute/path/to/prsna-mcp/dist/index.js"],
        "env": {
          "PRSNA_API_TOKEN": "prsna_your_generated_token_here"
        }
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible tools, use:

• Command: node /path/to/prsna-mcp/dist/index.js
• Environment: Set PRSNA_API_TOKEN
• Transport: stdio

Usage Examples

Basic Authentication

// Test your connection
await prsna_login({ token: "your-api-token" })

List Profiles

// Get first 10 profiles
await list_personality_profiles({ limit: 10, offset: 0 })

// Get next page
await list_personality_profiles({ limit: 10, offset: 10 })

Search for People

// Search by name
await search_personality_profiles({ query: "John Smith" })

// Search by company
await search_personality_profiles({ query: "Acme Corp" })

// Search by job title
await search_personality_profiles({ query: "Product Manager" })

Get Detailed Context

// By profile ID
await get_personality_context({ profileId: "profile-id-123" })

// By name
await get_personality_context({ name: "Sarah Johnson" })

Communication Tips

// General communication tips
await get_communication_tips({ name: "Alex Thompson" })

// Scenario-specific tips
await get_communication_tips({ 
  name: "Alex Thompson",
  scenario: "feedback meeting"
})

// Other scenarios: "project collaboration", "conflict resolution", "brainstorming session"

Quick @Mention Lookup

// Fast lookup for mentions
await mention_person({ name: "Maria Garcia" })

Your Own Profile

// Get your personality profile
await my_personality_profile({})

Response Format

All tools return responses in this format:

{
  "success": true,
  "data": {
    // Tool-specific response data
  }
}

Error responses:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message"
}

Personality Dimensions

PRSNA analyzes personality across five key dimensions:

| Dimension | Poles | Description | |-----------|--------|-------------| | Expression | Internal ↔ External | How people process and share thoughts | | Decision Making | Logic ↔ Feeling | Primary decision-making criteria | | Adaptability | Structured ↔ Adaptive | Preference for planning vs. flexibility | | Work Style | Process-Driven ↔ Results-Driven | Focus on methodology vs. outcomes | | Work Tempo | Fast-Paced ↔ Deliberate-Paced | Preferred speed of work and decisions |

Caching

The MCP server implements intelligent caching:

• Profile Data: 1 hour TTL
• Search Results: 15 minutes TTL
• User Profile: 24 hours TTL
• Maximum Cache Size: 1000 entries

Cache automatically cleans up expired entries every 5 minutes.

Logging

Logging levels (set via LOG_LEVEL environment variable):

• DEBUG: Detailed debugging information
• INFO: General information (default)
• WARN: Warning messages
• ERROR: Error messages only

Logs include timestamps, levels, and structured data for easy debugging.

Troubleshooting

Common Issues

"PRSNA_API_TOKEN environment variable is required"

• Ensure your .env file contains a valid PRSNA API token
• Contact PRSNA support if you need an API token

"Authentication failed"

• Verify your API token is correct and not expired
• Check that you have access to the PRSNA API

"No profile found for name"

• Check spelling and try partial names
• Use search_personality_profiles for broader matching
• Ensure the person has a saved profile in your PRSNA account

"Failed to connect to PRSNA API"

• Check your internet connection
• Verify the API URL in your configuration
• Check if PRSNA services are operational

Debug Mode

Run with debug logging:

LOG_LEVEL=debug npm run start

Cache Issues

Clear cache by restarting the server:

# Stop and restart the MCP server

Development

Project Structure

prsna-mcp/
├── src/
│   ├── api/
│   │   ├── client.ts      # PRSNA API client
│   │   └── types.ts       # TypeScript interfaces
│   ├── cache/
│   │   └── cache.ts       # Caching implementation
│   ├── tools/
│   │   ├── auth.ts        # Authentication tool
│   │   ├── profiles.ts    # Profile management tools
│   │   ├── context.ts     # Communication tools
│   │   ├── mention.ts     # @mention functionality
│   │   └── index.ts       # Tool exports
│   ├── utils/
│   │   ├── logger.ts      # Logging utilities
│   │   └── constants.ts   # Configuration constants
│   └── index.ts           # Main MCP server
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build      # Compile TypeScript
npm run dev        # Watch mode development
npm run start      # Start the server
npm run test       # Test the server
npm run clean      # Clean build artifacts

Adding New Tools

1. Create tool function in appropriate file under src/tools/
2. Add tool definition with proper schema
3. Export tool in src/tools/index.ts
4. Update documentation

API Reference

Tool Schemas

Each tool accepts specific parameters defined by JSON schemas. See the source code for detailed schemas, or use the ListTools MCP request to get current schemas.

Error Codes

• 401: Authentication failed
• 404: Profile not found
• 429: Rate limit exceeded
• 500: Internal server error

Support

• Documentation: This README
• Issues: Report issues with detailed error logs
• PRSNA API: Contact PRSNA support for API access

License

MIT License - see LICENSE file for details.

Version: 1.0.0 Last Updated: December 2024