Getting Started

Overview

The Carposé MCP (Model Context Protocol) server provides AI assistants with access to your dealership's vehicle inventory, employee data, and store information.

Key Features:

• ✅ Universal HTTP Access - Works with any MCP-compatible client

• ✅ No Installation Required - Serverless deployment via Cloudflare Workers

• ✅ Secure Authentication - API key-based access control

• ✅ Real-time Data - Direct connection to your Carposé database

• ✅ Rich Querying - Advanced filtering, pagination, and sorting

• ✅ Multi-tenant Support - Each API key scopes data to your organization

Example Usage

Here are some example queries you can ask your AI assistant:

Employee Queries

• "Show me all employees in the sales team"

• "Find the contact information for managers (Geschäftsführer)"

• "List employees at the Munich store"

Vehicle Queries

• "Show me all electric vehicles under €50,000"

• "List BMW vehicles with less than 50,000km mileage"

• "Find all vehicles built after 2020, sorted by price"

• "Show me vehicles at the Berlin store with automatic transmission"

Inventory Queries

• "What manufacturers do we currently have in stock?"

• "List all available models from Mercedes-Benz"

• "Which fuel types are available in our inventory?"

Tips for Best Results

Use Pagination to Avoid Large Responses

When listing vehicles, always use pagination to avoid overwhelming responses:

"List the first 10 vehicles, sorted by price"

Your AI assistant will automatically use itemsPerPage: 10 to keep responses manageable.

Combine Filters for Precise Results

You can combine multiple filters:

"Show me diesel vehicles from BMW or Audi, built between 2020 and 2024, priced under €40,000, with less than 80,000km, sorted by mileage ascending"

Navigate Results with Hydra Pagination

The server returns responses in Hydra JSON-LD format with pagination links. Your AI assistant can automatically:

• See total item counts

• Navigate to next/previous pages

• Jump to first/last pages

Just ask naturally:

"Show me the next page of results"

Troubleshooting

AI assistant doesn't recognize the Carposé tools

Problem: Your AI assistant responds "I don't have access to Carposé tools"

Solutions:

1. Verify the configuration file/settings are correct for your client

2. Check that the JSON syntax is valid (use a JSON validator if using config files)

3. Ensure your client was restarted after editing the configuration

4. Check that your API key is correct (no extra spaces or quotes)

5. Test the connection by calling the health endpoint: curl https://mcp.carpose.de/health

"Authentication required" error

Problem: Tools return "X-CARPOSE-API-KEY header is required"

Solutions:

1. Verify your API key is correctly set in the headers section

2. Make sure the key is wrapped in quotes: "X-CARPOSE-API-KEY": "your_key"

3. Contact your administrator to verify the API key is still valid

Configuration Examples

Basic Configuration (Claude Desktop - Single Tenant)

{
  "mcpServers": {
    "carpose": {
      "url": "https://mcp.carpose.de",
      "transport": {
        "type": "http"
      },
      "headers": {
        "X-CARPOSE-API-KEY": "abc123xyz456"
      }
    }
  }
}

Multiple Environments (Development & Production)

{
  "mcpServers": {
    "carpose-prod": {
      "url": "https://mcp.carpose.de",
      "transport": {
        "type": "http"
      },
      "headers": {
        "X-CARPOSE-API-KEY": "prod_api_key_here"
      }
    },
    "carpose-dev": {
      "url": "https://mcp-dev.carpose.workers.dev",
      "transport": {
        "type": "http"
      },
      "headers": {
        "X-CARPOSE-API-KEY": "dev_api_key_here"
      }
    }
  }
}

This allows you to switch between production and development environments.

Environment Variables (For Custom Integrations)

If you're building a custom integration, you can store the API key in environment variables:

# .env file
CARPOSE_MCP_URL=https://mcp.carpose.de
CARPOSE_API_KEY=your_api_key_here

Then reference them in your code:

const transport = new HttpClientTransport({
  url: process.env.CARPOSE_MCP_URL,
  headers: {
    'X-CARPOSE-API-KEY': process.env.CARPOSE_API_KEY
  }
});