MCP Server

Model Context Protocol server for Mapfolio - Enable AI assistants to interact with Mapfolio data

Overview

The Mapfolio MCP Server is a Model Context Protocol (MCP) server that enables AI assistants and other MCP-compatible clients to interact with Mapfolio's data and operations. It provides programmatic access to companies, projects, users, LinkedIn profiles, and administrative functions.

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely access external data sources and tools. MCP servers expose capabilities through a standardized interface, allowing AI assistants to:

  • Query and retrieve data
  • Perform operations
  • Access resources
  • Integrate with external systems

Features

The Mapfolio MCP Server provides comprehensive functionality:

Company Data

  • Search companies with advanced filters
  • Get company details by ID
  • Retrieve companies by canton and starting letter
  • Get random companies for sampling
  • Access company visit statistics

Project Management

  • Create and manage projects
  • List and filter user projects
  • Update project details
  • Delete projects
  • Add and remove companies from projects

User Profiles

  • Get user profile information
  • Update profile settings
  • List user projects
  • Manage API keys

LinkedIn Integration

  • Get LinkedIn profile data
  • Search LinkedIn profiles
  • Access connection information
  • View profile version history
  • Get LinkedIn company data

Administrative Operations

  • List all users (admin only)
  • Create new users (admin only)
  • Manage API keys (admin only)
  • Access admin dashboard statistics

Statistics

  • Get aggregated company statistics
  • View canton-level counts
  • Access letter-based counts
  • Get two-letter combination statistics

Installation

Prerequisites

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • Access to Mapfolio Supabase instance

Setup

  1. Install dependencies:
cd mcp-server
npm install
  1. Configure environment variables:
cp .env.example .env

Edit .env and configure:

# Mapfolio API URL (defaults to https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Transport type: 'stdio' (default) or 'http' for remote access
MCP_TRANSPORT=stdio

# HTTP port (only used when MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Optional: Default authentication (can be provided via MCP context or HTTP headers)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here
  1. Build the server:
npm run build

Usage

Running the Server

Local Development (stdio transport)

The MCP server uses stdio transport by default (standard MCP protocol):

npm start

For development with auto-reload:

npm run dev

HTTP Transport (for remote access)

To run the server with HTTP transport for local testing:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

This starts an HTTP server on port 3001 that accepts JSON-RPC 2.0 requests over HTTP POST.

Vercel Deployment (Remote Access)

The MCP server is automatically available via HTTP when deployed to Vercel:

  • Endpoint: https://your-app.vercel.app/api/mcp
  • Protocol: JSON-RPC 2.0 over HTTP POST
  • Authentication: Via X-API-Key header or Authorization: Bearer <token> header

Example request:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

MCP Client Configuration

Claude Desktop

Local deployment:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Configure via MCP settings:

  • Command: node
  • Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
  • Environment variables:
    • MAPFOLIO_API_URL: https://mapfolio.app
    • MAPFOLIO_API_KEY: Your API key (optional)

Authentication

The server supports two authentication methods:

API Key Authentication

API keys are prefixed with mapf_ and can be:

  • Set via MAPFOLIO_API_KEY environment variable
  • Passed per-request via apiKey parameter in tool calls

JWT Token Authentication

Supabase JWT tokens can be:

  • Set via MAPFOLIO_JWT_TOKEN environment variable
  • Passed per-request via jwtToken parameter in tool calls

Authentication Priority

  1. HTTP Transport: Headers (X-API-Key or Authorization) take precedence
  2. Per-request credentials (apiKey or jwtToken in tool arguments)
  3. Environment variables (MAPFOLIO_API_KEY or MAPFOLIO_JWT_TOKEN)

HTTP Transport Authentication

When using the HTTP endpoint (/api/mcp), authentication is provided via HTTP headers:

  • API Key: X-API-Key: mapf_your_api_key
  • JWT Token: Authorization: Bearer your_jwt_token

Available Tools

The server provides 30+ tools across 6 categories:

Company Tools

  • search_companies - Search with filters
  • get_company - Get company by ID
  • get_companies_by_canton_letter - Get by canton and letter
  • get_random_companies - Get random samples
  • get_company_visits - Get visit statistics

Project Tools

  • create_project - Create new project
  • list_projects - List user projects
  • get_project - Get project details
  • update_project - Update project
  • delete_project - Delete project
  • add_companies_to_project - Add companies
  • remove_companies_from_project - Remove companies

User Tools

  • get_user_profile - Get profile
  • update_user_profile - Update profile
  • get_user_projects - List projects
  • get_user_api_keys - List API keys

LinkedIn Tools

  • get_linkedin_profile - Get profile
  • search_linkedin_profiles - Search profiles
  • get_linkedin_connections - Get connections
  • get_linkedin_profile_versions - Get version history
  • get_linkedin_companies - Get company data

Admin Tools (Admin Only)

  • list_all_users - List all users
  • create_user - Create user
  • get_user_details - Get user details
  • list_api_keys - List all API keys
  • create_api_key - Create API key
  • revoke_api_key - Revoke API key
  • get_admin_stats - Get admin statistics

Statistics Tools

  • get_company_stats - Get aggregated stats
  • get_canton_counts - Get canton counts
  • get_letter_counts - Get letter counts
  • get_two_letter_counts - Get two-letter counts

Resources

The server provides resource-based access:

  • mapfolio://company/{id} - Company data
  • mapfolio://project/{id} - Project data
  • mapfolio://user/{id} - User profile
  • mapfolio://linkedin-profile/{id} - LinkedIn profile

Resources can include authentication via query parameters:

  • mapfolio://company/{id}?apiKey=mapf_...
  • mapfolio://company/{id}?jwtToken=...

Example Usage

Search Companies

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Create Project

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Get Company Details

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Error Handling

All tools return errors in a consistent format:

{
  "error": "Error message"
}

Common error scenarios:

  • 401 Unauthorized: Invalid or missing authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server-side error

API-Only Architecture

The MCP server uses HTTP requests to mapfolio.app instead of direct database access. This means:

  • ✅ No Supabase credentials needed - Works with just API URL and API key
  • ✅ Easy Vercel deployment - Deploy as serverless function
  • ✅ Secure - All requests go through Mapfolio's API with authentication
  • ✅ Scalable - Benefits from Mapfolio's API rate limiting and caching

Currently Available via API

  • ✅ Company search and retrieval
  • ✅ Company statistics (canton counts, letter counts)
  • ✅ Random companies
  • ✅ Company visits

Coming Soon (Requires API Endpoints)

  • ⏳ Project management (create, list, update, delete)
  • ⏳ User profile management
  • ⏳ LinkedIn profile access
  • ⏳ Admin operations

These features will return helpful error messages until the API endpoints are created.

Security Considerations

  1. API Keys: Store securely, never commit to version control
  2. JWT Tokens: Tokens expire, handle refresh appropriately
  3. API Rate Limiting: Respects Mapfolio's API rate limits
  4. HTTPS Only: Always use HTTPS for API requests
  5. Admin Operations: Require explicit admin authentication (when endpoints are available)

Development

Type Checking

npm run type-check

Building

npm run build

Development Mode

npm run dev

Documentation

For complete documentation, see the MCP Server README.

Support

For issues or questions:

License

MIT