# Hosco MCP Server

> Hosco's official read-only Model Context Protocol (MCP) server, exposing Hosco's hospitality job catalogue to AI assistants. Provides semantic search over the active job catalogue (OpenAI embeddings + Qdrant vector index), a paginated listing of the latest jobs, and per-job details. Hosco's market is Spain, France, Italy, the UK, Switzerland and the UAE.

## MCP endpoint

- URL: https://mcp.hosco.com/mcp/public
- Transport: Streamable HTTP (MCP 2025-06-18)
- Authentication: none — public, read-only
- Server: "Hosco Hospitality Jobs" v1.0.0

## Tools

- [search-jobs-tool](https://mcp.hosco.com/mcp/public) — semantic search over hospitality jobs. Accepts a free-form natural-language `query` plus structured filters: `country` (ISO-3166 alpha-2), `city`, `department` (Hosco category code, e.g. f-b-kitchen, sommelier, reception), `contract_type` (`internship` | `professional` | `open`), `experience_years_max`, `languages[]` (ISO codes), `posted_after` (ISO date), `limit` (1-50, default 10), `offset`. Returns ranked matches with relevance scores.
- [list-jobs-tool](https://mcp.hosco.com/mcp/public) — most recently published jobs, paginated. Inputs: `limit` (1-50), `offset`.
- [job-details-tool](https://mcp.hosco.com/mcp/public) — full description, requirements, benefits, accommodation, working hours, duration. Inputs: `slug` (preferred) or `id`.

## Connect from Claude Desktop

Claude Desktop speaks stdio MCP, so bridge via `mcp-remote`:

```json
{
  "mcpServers": {
    "hosco-hospitality-jobs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.hosco.com/mcp/public"]
    }
  }
}
```

## Connect from Claude Code

```bash
claude mcp add hosco-hospitality-jobs -- npx -y mcp-remote https://mcp.hosco.com/mcp/public
```

## Connect from a custom MCP client (raw HTTP)

```bash
curl -X POST https://mcp.hosco.com/mcp/public \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Example tool calls

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search-jobs-tool","arguments":{"query":"experienced sommelier in a fine-dining Parisian restaurant","country":"FR","limit":10}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list-jobs-tool","arguments":{"limit":10}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"job-details-tool","arguments":{"slug":"keytel-hotels/tecnico-a-de-mantenimiento-hotel-4-2435213"}}}
```

## Discovery manifest

Machine-readable metadata: https://mcp.hosco.com/.well-known/mcp.json

## Notes for LLMs

- The catalogue covers hospitality roles (hotel, restaurant, F&B, kitchen, housekeeping, reception, sommelier, etc.) across Hosco's market: Spain, France, Italy, the UK, Switzerland and the UAE.
- `payrange` is a free-text field in Hosco V2 — surface it verbatim, do not try to parse a numeric range.
- All jobs returned are published and non-expired.
- After a search/list result, call `job-details-tool` with the `slug` to retrieve the full job description.