# Client setup

Any MCP host can use the server in one of two ways:

- **stdio** — the host launches `alhorno-mcp serve` as a child process. Works offline, needs no
  port, and is the best choice for a laptop.
- **Streamable HTTP** — the host connects to `POST /mcp` over a URL. Required for hosted clients
  such as ChatGPT connectors, convenient for a team instance.

The snippets below use `/absolute/path/to/al_horno_con_papa_mcp`; replace it with your checkout.
If you installed the wheel with `uv tool install`, replace the whole command with
`["alhorno-mcp", "serve"]`.

## OpenCode

OpenCode (V2) reads MCP servers from `opencode.json` (or `opencode.jsonc`) in the project or in
`~/.config/opencode/`, under `mcp.servers`:

=== "Local process"

    ```json
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "servers": {
          "al-horno-con-papa": {
            "type": "local",
            "command": [
              "uv",
              "run",
              "--directory",
              "/absolute/path/to/al_horno_con_papa_mcp",
              "alhorno-mcp",
              "serve"
            ]
          }
        }
      }
    }
    ```

=== "Remote endpoint"

    ```json
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "servers": {
          "al-horno-con-papa": {
            "type": "remote",
            "url": "https://mcp.alhornoconpapa.com.ar/mcp"
          }
        }
      }
    }
    ```

OpenCode watches the configuration and reloads the server when it changes; `/reload` forces a full
reload. A server is connected by default, and `"disabled": true` keeps it configured without
connecting it. Check the state from any project:

```text
$ opencode mcp list
✓ al-horno-con-papa  connected
```

!!! tip "Where the six tools show up"

    OpenCode reaches MCP tools through **Code Mode** by default, so they are not separate entries in
    the model's tool list: the agent calls them as
    `tools["al-horno-con-papa"].search_recipes(...)` inside `execute`. To publish them as native
    tools named `al-horno-con-papa_search_recipes`, `al-horno-con-papa_get_recipe` and so on, set
    `"codemode": false` on the server entry. Native tools send their full schema on every request,
    which is why Code Mode is the default.

## Claude Code

```bash
# Local process
claude mcp add --transport stdio al-horno-con-papa -- \
  uv run --directory /absolute/path/to/al_horno_con_papa_mcp alhorno-mcp serve

# Remote endpoint
claude mcp add --transport http al-horno-con-papa https://mcp.alhornoconpapa.com.ar/mcp
```

Verify with `claude mcp list`. Use `--scope project` to write `.mcp.json` in the repository so the
whole team shares the configuration.

## Claude Desktop

Edit `claude_desktop_config.json` and restart the app:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "al-horno-con-papa": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/al_horno_con_papa_mcp",
        "alhorno-mcp",
        "serve"
      ]
    }
  }
}
```

Claude Desktop launches stdio servers only. For the hosted endpoint, use a client that supports
remote MCP.

## ChatGPT

ChatGPT connects to **remote** MCP servers through connectors, so it needs the public HTTPS
endpoint. This requires a paid plan and developer mode:

1. Open **Settings → Connectors → Advanced settings** and enable **Developer mode**.
2. Choose **Create** and enter a name plus the URL
   `https://mcp.alhornoconpapa.com.ar/mcp`.
3. Start a chat, open the tools menu and enable the connector for that conversation.

There is no authentication to configure: the endpoint is public and read-only.

## Gemini CLI

Add the server to `~/.gemini/settings.json`:

=== "Local process"

    ```json
    {
      "mcpServers": {
        "al-horno-con-papa": {
          "command": "uv",
          "args": [
            "run",
            "--directory",
            "/absolute/path/to/al_horno_con_papa_mcp",
            "alhorno-mcp",
            "serve"
          ]
        }
      }
    }
    ```

=== "Remote endpoint"

    ```json
    {
      "mcpServers": {
        "al-horno-con-papa": {
          "httpUrl": "https://mcp.alhornoconpapa.com.ar/mcp"
        }
      }
    }
    ```

Run `/mcp` inside Gemini CLI to confirm that the server is connected.

## Cursor

Cursor reads `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` globally:

=== "Local process"

    ```json
    {
      "mcpServers": {
        "al-horno-con-papa": {
          "command": "uv",
          "args": [
            "run",
            "--directory",
            "/absolute/path/to/al_horno_con_papa_mcp",
            "alhorno-mcp",
            "serve"
          ]
        }
      }
    }
    ```

=== "Remote endpoint"

    ```json
    {
      "mcpServers": {
        "al-horno-con-papa": {
          "url": "https://mcp.alhornoconpapa.com.ar/mcp"
        }
      }
    }
    ```

Enable the server under **Settings → MCP** and confirm it reports six tools.

## Prompts that work well

Recipe names, ingredient names and tags are **Spanish**, because the catalog is Spanish. The
model can translate around that, but the tool arguments should stay in Spanish:

- "¿Qué puedo cocinar con huevo, harina y leche?"
- "Busca recetas de torta de chocolate y dame la mejor."
- "Dame una receta vegana al azar."
- "Listá los tags y buscá recetas de postres fáciles."

The server also sends the model a short instruction block during initialization asking it to start
with `search_recipes`, call `get_recipe` only for the recipes it will describe, and always include
the recipe's `site_url`.

## Troubleshooting

| Symptom | Cause |
| --- | --- |
| The host exits immediately and logs `error: ...` | Settings error or missing snapshot; run the same command in a terminal to see the message. |
| `421 Misdirected Request` | The `Host` header is not in `ALHORNO_ALLOWED_HOSTS`; add the public hostname. |
| Tools never appear | Check the connection first (`opencode mcp list`); under Code Mode the tools are grouped inside `execute` instead of the native tool list. Otherwise the host is running a different command or file: check its MCP log and use the absolute checkout path. |
| `Unknown tag 'pollo'` | Tags are case-sensitive: the catalog has `Pollo`. Call `list_tags` first. |
