# Fixatia MCP Server - Full Documentation

> Fixatia provides an MCP (Model Context Protocol) server for searching European real estate auction properties. The server allows AI assistants to search properties, retrieve detailed information, and understand available filter options.

## Server Information

- Name: fixatia-property-search
- Version: 0.1.0
- Protocol: MCP (Model Context Protocol)
- Protocol Version: 2024-11-05
- Transport: HTTP
- Base URL: https://mcp.fixatia.com/api/mcp

## Quick Start for Claude Desktop

Add to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "fixatia": {
      "url": "https://mcp.fixatia.com/api/mcp"
    }
  }
}
```

Then restart Claude Desktop and ask: "Search for properties in Portugal under 150,000 euros with ROI above 20%"

---

## Tools Reference

### 1. search_properties

Search for real estate auction properties across Europe. Filter by country, city, price, property type, ROI potential, and more. Returns a list of matching properties with basic details (title, location, pricing, images). Use get_property for full description.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | No | Text search for property title, city, or region |
| country | string | No | Country code: es (Spain), pt (Portugal), it (Italy), fr (France), de (Germany), hr (Croatia) |
| region | string | No | Region name within the country |
| city | string | No | City name |
| propertyType | string | No | One of: APARTMENT, HOUSE, VILLA, LAND, COMMERCIAL |
| minPrice | number | No | Minimum auction price in EUR |
| maxPrice | number | No | Maximum auction price in EUR |
| minRoi | number | No | Minimum ROI percentage (e.g., 20 for 20%) |
| bedrooms | number | No | Minimum number of bedrooms |
| maxResults | number | No | Maximum number of results to return (default: 10, max: 50) |
| sortBy | string | No | One of: newest, price-low, price-high, roi-high, auction-soonest |
| locale | string | No | Language for titles/descriptions (default: en) |

#### Example Request

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_properties",
    "arguments": {
      "country": "pt",
      "maxPrice": 150000,
      "minRoi": 20,
      "maxResults": 5
    }
  },
  "id": 1
}
```

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": {
        "totalCount": 12,
        "results": [
          {
            "id": "b45dc4fc14134da69e9f800f8",
            "title": "2-Bedroom Apartment in Lisbon",
            "country": "pt",
            "region": "Lisboa",
            "city": "Lisboa",
            "propertyType": "APARTMENT",
            "auctionPrice": 120000,
            "marketValue": 165000,
            "potentialRoi": 26.5,
            "bedrooms": 2,
            "bathrooms": 1,
            "squareMeters": 75,
            "auctionDate": "2026-02-15",
            "primaryImage": "https://fixatia.com/images/property-123.jpg"
          }
        ]
      }
    }]
  }
}
```

---

### 2. get_property

Get full details of a specific property by its ID. Returns comprehensive information including description, images, location coordinates, renovation estimates, and auction details.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | The property ID (obtained from search results) |
| locale | string | No | Language for title/description (default: en) |

#### Example Request

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_property",
    "arguments": {
      "id": "b45dc4fc14134da69e9f800f8",
      "locale": "en"
    }
  },
  "id": 2
}
```

#### Response Fields

The response includes:
- id, externalId, source, sourceUrl
- country, region, city, address, postalCode
- latitude, longitude
- propertyType
- title, description (in requested locale)
- bedrooms, bathrooms, squareMeters, plotSize, yearBuilt, floors
- auctionPrice, marketValue, startingBid
- auctionDate, auctionEndDate
- potentialRoi
- energyRating
- renovationCostLow, renovationCostHigh, estimatedValueAfter
- status
- images (array with url, alt, isPrimary, order)

---

### 3. get_filter_options

Get available filter options including list of countries, regions, cities, property types, and price/ROI ranges. Useful for understanding what search parameters are available before performing a search.

#### Parameters

None required.

#### Example Request

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_filter_options",
    "arguments": {}
  },
  "id": 3
}
```

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{
      "type": "text",
      "text": {
        "countries": [
          { "code": "pt", "name": "Portugal", "propertyCount": 45 },
          { "code": "es", "name": "Spain", "propertyCount": 120 },
          { "code": "it", "name": "Italy", "propertyCount": 89 },
          { "code": "de", "name": "Germany", "propertyCount": 67 },
          { "code": "fr", "name": "France", "propertyCount": 34 },
          { "code": "hr", "name": "Croatia", "propertyCount": 23 }
        ],
        "propertyTypes": [
          { "type": "APARTMENT", "count": 156 },
          { "type": "HOUSE", "count": 78 },
          { "type": "VILLA", "count": 23 },
          { "type": "LAND", "count": 45 },
          { "type": "COMMERCIAL", "count": 12 }
        ],
        "priceRange": { "min": 5000, "max": 800000 },
        "roiRange": { "min": -5, "max": 45 },
        "bedroomOptions": [1, 2, 3, 4, 5],
        "regionsAvailable": true,
        "citiesAvailable": true
      }
    }]
  }
}
```

---

### 4. send_property_inquiry

Send an inquiry about a property to express interest. **Requires OAuth 2.1 authentication with PKCE.**

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| propertyId | string | Yes | The property ID to inquire about |
| message | string | Yes | Inquiry message (minimum 10 characters) |

#### Authentication

OAuth 2.1 with PKCE is required for this tool. Include a Bearer token in the Authorization header.

#### Example Request (Authenticated)

```bash
curl -X POST https://mcp.fixatia.com/api/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "send_property_inquiry",
      "arguments": {
        "propertyId": "b45dc4fc14134da69e9f800f8",
        "message": "I am interested in this property. Is it still available?"
      }
    },
    "id": 4
  }'
```

#### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{
      "type": "text",
      "text": "Inquiry sent successfully! The property owner will be notified and may contact you."
    }]
  }
}
```

---

## Authentication (OAuth 2.1 with PKCE)

The `send_property_inquiry` tool requires OAuth 2.1 authentication with PKCE (Proof Key for Code Exchange) per MCP standards.

### OAuth 2.1 Flow

#### Step 1: Generate PKCE Values

```javascript
// Generate code_verifier (random 32-byte string, base64url encoded)
const codeVerifier = generateRandomString(32);

// Generate code_challenge (SHA-256 hash of verifier, base64url encoded)
const codeChallenge = base64url(sha256(codeVerifier));
```

#### Step 2: Authorization Request

```
GET /api/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_CALLBACK_URL
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &scope=mcp:inquiry
  &state=RANDOM_STATE
```

User is redirected to login (if not already authenticated), then back to your redirect_uri with an authorization code.

#### Step 3: Token Exchange

```bash
POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "YOUR_CALLBACK_URL",
  "client_id": "YOUR_CLIENT_ID",
  "code_verifier": "ORIGINAL_CODE_VERIFIER"
}
```

Response:
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "mcp:inquiry"
}
```

#### Step 4: Use Token

Include the access token in the Authorization header for protected requests:

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### Claude Desktop Configuration with Token

```json
{
  "mcpServers": {
    "fixatia": {
      "url": "https://mcp.fixatia.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}
```

### Alternative: Manual Token Generation

You can also generate API tokens directly from your account settings at https://fixatia.com/account (requires login).

### Token Features

- Tokens are valid for 30 days
- Tokens can be revoked at any time from your account
- Usage is tracked for security purposes
- Scope: mcp:inquiry

---

## HTTP API Reference

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/mcp | Server info and health check |
| POST | /api/mcp | JSON-RPC 2.0 requests |

### JSON-RPC Methods

| Method | Description |
|--------|-------------|
| initialize | Initialize MCP session |
| tools/list | List available tools |
| tools/call | Execute a tool |
| ping | Health check |

### cURL Example

```bash
curl -X POST https://mcp.fixatia.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_properties",
      "arguments": {
        "country": "pt",
        "maxPrice": 150000
      }
    },
    "id": 1
  }'
```

---

## Error Codes

Standard JSON-RPC 2.0 error codes:

| Code | Message | Description |
|------|---------|-------------|
| -32600 | Invalid Request | The JSON sent is not a valid request object |
| -32601 | Method not found | The method does not exist |
| -32602 | Invalid params | Invalid method parameters |
| -32603 | Internal error | Internal JSON-RPC error |

### Error Response Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: Property ID is required"
  }
}
```

---

## Supported Languages

The `locale` parameter accepts these language codes:

| Code | Language |
|------|----------|
| en | English |
| de | German |
| fr | French |
| es | Spanish |
| it | Italian |
| pt | Portuguese |
| nl | Dutch |
| pl | Polish |
| el | Greek |
| ro | Romanian |
| cs | Czech |
| hu | Hungarian |
| zh | Chinese |
| ar | Arabic |
| ru | Russian |
| ja | Japanese |
| ko | Korean |
| hr | Croatian |

---

## Country Codes

| Code | Country |
|------|---------|
| es | Spain |
| pt | Portugal |
| it | Italy |
| fr | France |
| de | Germany |
| hr | Croatia |

---

## Property Types

| Type | Description |
|------|-------------|
| APARTMENT | Apartment or flat |
| HOUSE | House |
| VILLA | Villa |
| LAND | Land or plot |
| COMMERCIAL | Commercial property |

---

## Sort Options

| Value | Description |
|-------|-------------|
| newest | Most recently added first |
| price-low | Lowest price first |
| price-high | Highest price first |
| roi-high | Highest ROI potential first |
| auction-soonest | Auctions ending soonest first |

---

## Links

- Website: https://fixatia.com
- MCP Documentation: https://fixatia.com/developers/mcp
- Contact: https://fixatia.com/contact
- MCP Protocol: https://modelcontextprotocol.io