# Agent registration

Agents can self-register and receive an API token immediately.
Listed MCP services are **auto-approved**. A system admin may suspend the
agent account or move service access back to `pending`.

Optional identity metadata (`actor_kind`, `org_label`) may be sent for analytics
and future billing — **never required**. Permissions come from
`approved_services`, not from self-declared claims.

## Endpoint

`POST https://mcp.glc-rag.hu/api/auth/register`

## Request

```http
POST https://mcp.glc-rag.hu/api/auth/register
Content-Type: application/json

{
  "email": "agent@example.com",
  "password": "choose-a-strong-password",
  "account_type": "agent",
  "actor_kind": "application",
  "org_label": "Acme Kft."
}
```

### Optional fields

| Field | Values | Notes |
|-------|--------|-------|
| `actor_kind` | `person`, `application`, `enterprise_agent`, `subagent` | Soft label; omit if unknown |
| `org_label` | string ≤200 chars | Organization the actor acts on behalf of |

## Response (selected fields)

```json
{
  "user": {
    "email": "agent@example.com",
    "account_type": "agent",
    "status": "active",
    "role": "org_admin",
    "actor_kind": "application",
    "org_label": "Acme Kft."
  },
  "approved_services": ["hello", "geo", "fetch", "docs", "shot"],
  "api_token": "mcp_...",
  "access_token": "<JWT for web/API>",
  "token_type": "bearer"
}
```

Save `api_token` — it authenticates the MCP endpoint.

## Call MCP

```http
POST https://mcp.glc-rag.hu/mcp
Authorization: Bearer mcp_...
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

## curl

```bash
curl -sS -X POST 'https://mcp.glc-rag.hu/api/auth/register' \
  -H 'Content-Type: application/json' \
  -d '{"email":"agent@example.com","password":"choose-a-strong-password","account_type":"agent","actor_kind":"application","org_label":"Acme Kft."}'
```

## Cursor `mcp.json`

```json
{
  "mcpServers": {
    "glc-mcp": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Human vs agent

| | Human | Agent |
|--|-------|-------|
| `account_type` | `human` (default) | `agent` |
| Service access | Request in Admin → system-admin approve | Auto-approved on register |
| API token | Create in Admin after approval | Returned as `api_token` |
| Suspension | System admin can suspend | Same |
| `actor_kind` / `org_label` | Optional (human defaults `person`) | Optional metadata |

## Links

- Web register (check **Register as agent**): `https://mcp.glc-rag.hu/register`
- This guide: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/agent.md`
- Catalog: `https://mcp.glc-rag.hu/guide/catalog.md`
- Agent index: `https://mcp.glc-rag.hu/llms.txt`
- MCP: `https://mcp.glc-rag.hu/mcp`


---

# MCP service catalog

Platform: https://mcp.glc-rag.hu

## Services

- [Hello](https://mcp.glc-rag.hu/guide/hello.md) — Smoke-test MCP service (hello world).
- [Geo](https://mcp.glc-rag.hu/guide/geo.md) — GeoNames-backed geospatial MCP: countries, cities, admin regions, marine, POIs (airports, peaks, lakes, …), distance and nearby search.
- [Fetch](https://mcp.glc-rag.hu/guide/fetch.md) — Fetch a public URL and return its main content as markdown (Readability + markdownify, same approach as the official MCP fetch server).
- [Docs](https://mcp.glc-rag.hu/guide/docs.md) — Extract text and tables from PDF, DOCX, XLSX (and plain text/CSV). Scanned PDFs use Tesseract OCR (hun/eng/deu).
- [Shot](https://mcp.glc-rag.hu/guide/shot.md) — Render a public URL to a PNG/JPEG screenshot (Playwright + system Chromium).

## Agent registration

Agents: POST `https://mcp.glc-rag.hu/api/auth/register` with
`{"account_type":"agent"}` → auto-approved services + `api_token`.

Full guide: [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent)
Markdown: [https://mcp.glc-rag.hu/guide/agent.md](https://mcp.glc-rag.hu/guide/agent.md)

## Connect

Streamable HTTP: `https://mcp.glc-rag.hu/mcp`

Header: `Authorization: Bearer <api_token>`


# Hello

Minimal hello-world service to verify MCP connectivity and API keys.

**Service id:** `hello`  
**Version:** `0.1.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site, request this service in Admin,
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "hello": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `hello_ping`

Return a greeting message and server timestamp.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Optional name to greet (default: world)"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "name": "Attila"
}
```

```json
{}
```

## Usage notes

Call `hello_ping` after system-admin approves the hello service for your org.

## Errors / limits

Unauthorized tools are hidden from tools/list when the service is not approved.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/hello.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://hello`


---

# Geo

Read-only access to rag_dev.geo_entities (~2.5M GeoNames rows). Resolve names, inspect countries/cities/admin/marine/places, coastal filters, haversine distance, nearby radius search, airport IATA lookup, and embedding-neighbor search.

**Service id:** `geo`  
**Version:** `0.2.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site, request this service in Admin,
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "geo": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `geo_status`

Geo DB health, read-only mode, and row counts by entity_type.

**Input schema:**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Examples:**

```json
{}
```

### `geo_resolve`

Resolve a name, ISO2/ISO3, or IATA code to geo entities (best matches).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "country_code": {
      "type": "string",
      "description": "ISO2 filter"
    },
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "query": "Budapest",
  "entity_type": "city"
}
```

```json
{
  "query": "HU"
}
```

```json
{
  "query": "BUD"
}
```

### `geo_get`

Full entity profile by geoname_id (columns + complete payload).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    }
  },
  "required": [
    "geoname_id"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "geoname_id": 3054643
}
```

### `geo_text_search`

Fuzzy text search (pg_trgm) over names and search_text.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "query": "Balaton",
  "entity_type": "place"
}
```

### `geo_semantic_search`

Embedding-space neighbors around the best name match (uses stored e5 vectors; no write to DB). Falls back to text search if anchor has no embedding.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "query": "Budapest",
  "entity_type": "city",
  "limit": 10
}
```

### `geo_country_get`

Country facts by ISO2 or geoname_id (currency, languages, coastal flags, …).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "iso2": "HU"
}
```

### `geo_country_list`

List countries, optionally filtered by continent_code.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "continent_code": {
      "type": "string",
      "description": "e.g. EU, AS, AF"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 252,
      "default": 50
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "continent_code": "EU",
  "limit": 20
}
```

### `geo_country_neighbours`

Neighbouring countries via payload.neighbours ISO2 list.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "iso2": "HU"
}
```

### `geo_country_capital`

Resolve country capital via capital_geoname_id.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "iso2": {
      "type": "string"
    }
  },
  "required": [
    "iso2"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "iso2": "IT"
}
```

### `geo_admin1_list`

List admin1 regions for a country (e.g. Italian regions).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "country_code": "IT"
}
```

### `geo_admin1_get`

Get admin1 by admin_code (e.g. IT.03) or geoname_id.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "admin_code": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "admin_code": "IT.03"
}
```

### `geo_admin2_list`

List admin2 for a country, optionally under an admin1 short code.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string",
      "description": "Short code e.g. 03"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "country_code": "IT",
  "admin1_code": "03"
}
```

### `geo_admin2_get`

Get admin2 by admin_code or geoname_id.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "admin_code": {
      "type": "string"
    },
    "geoname_id": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{}
```

### `geo_cities_search`

Search cities with filters: country, admin1 short code, population, coastal_category, distance_to_coast_km, is_capital, name query.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string"
    },
    "min_population": {
      "type": "integer"
    },
    "max_population": {
      "type": "integer"
    },
    "coastal_category": {
      "type": "string",
      "enum": [
        "direct_coastal",
        "coastal",
        "near_coast",
        "inland"
      ]
    },
    "max_distance_to_coast_km": {
      "type": "number"
    },
    "is_capital": {
      "type": "boolean"
    },
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "country_code": "IT",
  "admin1_code": "03",
  "max_population": 500,
  "max_distance_to_coast_km": 5
}
```

### `geo_coastal_cities`

Shortcut for coastal city lists (distance and/or coastal_category).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string"
    },
    "max_distance_to_coast_km": {
      "type": "number",
      "default": 5
    },
    "coastal_category": {
      "type": "string",
      "enum": [
        "direct_coastal",
        "coastal",
        "near_coast",
        "inland"
      ]
    },
    "max_population": {
      "type": "integer"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "country_code"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "country_code": "IT",
  "admin1_code": "03",
  "max_distance_to_coast_km": 5
}
```

### `geo_region_cities`

Cities in an admin1 region (country_code + admin1 short code).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "country_code": {
      "type": "string"
    },
    "admin1_code": {
      "type": "string"
    },
    "min_population": {
      "type": "integer"
    },
    "max_population": {
      "type": "integer"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "country_code",
    "admin1_code"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "country_code": "IT",
  "admin1_code": "03",
  "min_population": 10000
}
```

### `geo_nearest_marine`

Precomputed nearest sea/bay for a city (nearest_marine_* + coastal fields).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    },
    "city_query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "city_query": "Rimini"
}
```

### `geo_marine_get`

Marine entity (sea, bay, …) by geoname_id or name query.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "geoname_id": {
      "type": "integer"
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "query": "Adriatic"
}
```

### `geo_distance`

Haversine distance (km) between two places (id or name). Countries use capital coords.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "from_id": {
      "type": "integer"
    },
    "from_query": {
      "type": "string"
    },
    "to_id": {
      "type": "integer"
    },
    "to_query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "from_query": "Budapest",
  "to_query": "Vienna"
}
```

### `geo_nearby`

Entities within radius_km of a center (id, name, or lat/lon). Optional type/kind filters.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "center_id": {
      "type": "integer"
    },
    "center_query": {
      "type": "string"
    },
    "latitude": {
      "type": "number"
    },
    "longitude": {
      "type": "number"
    },
    "radius_km": {
      "type": "number",
      "default": 30
    },
    "entity_type": {
      "type": "string",
      "enum": [
        "country",
        "city",
        "place",
        "admin1",
        "admin2",
        "marine"
      ]
    },
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "center_query": "Budapest",
  "radius_km": 40,
  "entity_type": "place",
  "place_kind": "airport"
}
```

### `geo_places_search`

Search POIs by place_kind (hill, mountain, peak, volcano, lake, lakes, reservoir, waterfall, …), country, name, elevation.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "country_code": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "min_elevation": {
      "type": "number"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "place_kind": "lake",
  "country_code": "HU",
  "limit": 10
}
```

### `geo_airport_lookup`

Find airports by IATA/ICAO, name, country, or near a city.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "iata": {
      "type": "string"
    },
    "icao": {
      "type": "string"
    },
    "query": {
      "type": "string"
    },
    "country_code": {
      "type": "string"
    },
    "near_query": {
      "type": "string"
    },
    "radius_km": {
      "type": "number",
      "default": 50
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "iata": "BUD"
}
```

```json
{
  "near_query": "Budapest",
  "radius_km": 60
}
```

### `geo_rank_places`

Rank places of a kind (e.g. highest peaks) optionally within a country.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "place_kind": {
      "type": "string",
      "enum": [
        "hill",
        "mountain",
        "peak",
        "volcano",
        "lake",
        "lakes",
        "reservoir",
        "waterfall",
        "island",
        "islands",
        "atoll",
        "airport",
        "heliport",
        "park",
        "nature_reserve",
        "wildlife_reserve",
        "pass",
        "ruin",
        "castle",
        "museum",
        "monument",
        "oilfield"
      ]
    },
    "country_code": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": [
    "place_kind"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "place_kind": "peak",
  "country_code": "IT",
  "limit": 5
}
```

### `geo_place_kinds`

List supported place_kind values and entity_type values.

**Input schema:**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Examples:**

```json
{}
```

## Usage notes

Prefer geo_resolve / geo_get for IDs, then specialized tools. Admin1 short codes (e.g. '03') + country_code bind to admin_code 'IT.03'. Coastal fields are precomputed on city rows. RAG database is never written.

## Errors / limits

Missing coords on countries → distance uses capital. Unknown names return empty results. Invalid API key → platform 401.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/geo.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://geo`


---

# Fetch

Remote web fetch for agents: given an http(s) URL, downloads the page, extracts the main article with Mozilla Readability, and returns clean markdown. Supports max_length / start_index pagination and optional raw HTML. Respects robots.txt; blocks private/local addresses (SSRF guard).

**Service id:** `fetch`  
**Version:** `0.1.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site, request this service in Admin,
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "fetch": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `fetch`

Fetches a URL from the internet and extracts its contents as markdown. Although originally you did not have internet access, this tool grants you access to public web pages. Returns title, markdown content, size, and truncation metadata (compatible with the official MCP fetch server).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "URL to fetch (http or https)"
    },
    "max_length": {
      "type": "integer",
      "description": "Maximum number of characters to return (default 5000).",
      "minimum": 1,
      "maximum": 1000000,
      "default": 5000
    },
    "start_index": {
      "type": "integer",
      "description": "Start returning output at this character index (use after a truncated fetch).",
      "minimum": 0,
      "default": 0
    },
    "raw": {
      "type": "boolean",
      "description": "Return raw page body without Readability simplification.",
      "default": false
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "url": "https://example.com"
}
```

```json
{
  "url": "https://example.com",
  "max_length": 2000
}
```

```json
{
  "url": "https://example.com",
  "start_index": 5000,
  "max_length": 5000
}
```

### `fetch_status`

Fetch service health and default limits.

**Input schema:**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Examples:**

```json
{}
```

## Usage notes

Call `fetch` with `url`. If `truncated` is true, call again with `start_index` = `next_start_index` to continue. Set `raw: true` for unsimplified HTML. Same extraction stack as @modelcontextprotocol/server-fetch (httpx + readabilipy + markdownify).

## Errors / limits

Non-http(s), private IPs, robots.txt disallow, HTTP ≥400, oversized body, or DNS failure → error object with `error` string. Invalid API key → platform 401.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/fetch.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://fetch`


---

# Docs

Document extraction for agents: download a public URL or pass base64, then return text/tables. PDF uses pdfplumber; empty/scanned pages fall back to poppler + Tesseract OCR with language packs (default hun+eng).

**Service id:** `docs`  
**Version:** `0.1.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site, request this service in Admin,
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "docs": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `docs_extract`

Extract text and tables from a document (pdf, docx, xlsx, txt, csv). Provide either a public http(s) URL or base64 content. For scanned PDFs, OCR runs automatically when little text is found.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public http(s) URL of the document"
    },
    "content_base64": {
      "type": "string",
      "description": "Raw document bytes as base64 (or data: URL)"
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint for type detection (e.g. report.pdf)"
    },
    "lang": {
      "type": "string",
      "description": "OCR languages, e.g. hun+eng (default hun+eng)",
      "default": "hun+eng"
    },
    "force_ocr": {
      "type": "boolean",
      "description": "Always OCR PDF pages even if embedded text exists",
      "default": false
    },
    "max_length": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000,
      "default": 20000
    },
    "start_index": {
      "type": "integer",
      "minimum": 0,
      "default": 0
    },
    "max_pages": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 50,
      "description": "Max PDF pages to process"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
}
```

```json
{
  "url": "https://example.com/scan.pdf",
  "lang": "hun+eng",
  "force_ocr": true
}
```

### `docs_status`

Docs service health, supported formats, and installed OCR languages.

**Input schema:**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Examples:**

```json
{}
```

## Usage notes

Call `docs_extract` with `url` or `content_base64`. Set `lang` to `hun`, `eng`, `deu`, or combinations like `hun+eng`. Use `force_ocr: true` for scanned PDFs. Paginate with `max_length` / `start_index`.

## Errors / limits

Unsupported type, SSRF-blocked URL, oversized body, missing OCR packs, or extract failure → `{error, is_error}`. Invalid API key → platform 401.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/docs.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://docs`


---

# Shot

Headless screenshot service for agents: navigate to a public http(s) URL and return a viewport or full-page image as base64. Uses Playwright against the server Chromium binary.

**Service id:** `shot`  
**Version:** `0.1.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site, request this service in Admin,
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "shot": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `screenshot`

Capture a screenshot of a public web page and return image_base64 plus metadata (title, final_url, dimensions).

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public http(s) URL to capture"
    },
    "width": {
      "type": "integer",
      "minimum": 320,
      "maximum": 1920,
      "default": 1280
    },
    "height": {
      "type": "integer",
      "minimum": 240,
      "maximum": 1080,
      "default": 720
    },
    "full_page": {
      "type": "boolean",
      "default": false,
      "description": "Capture full scrollable page"
    },
    "format": {
      "type": "string",
      "enum": [
        "png",
        "jpeg"
      ],
      "default": "png"
    },
    "quality": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "JPEG quality (ignored for png)"
    },
    "wait_until": {
      "type": "string",
      "enum": [
        "load",
        "domcontentloaded",
        "networkidle",
        "commit"
      ],
      "default": "domcontentloaded"
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 1000,
      "maximum": 60000,
      "default": 30000
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

**Examples:**

```json
{
  "url": "https://example.com"
}
```

```json
{
  "url": "https://example.com",
  "full_page": true,
  "format": "jpeg"
}
```

### `screenshot_status`

Screenshot service health and Chromium path.

**Input schema:**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Examples:**

```json
{}
```

## Usage notes

Call `screenshot` with `url`. Optional: `width`, `height`, `full_page`, `format` (png|jpeg), `wait_until` (domcontentloaded|load|networkidle). Private/local URLs are blocked (SSRF guard).

## Errors / limits

SSRF-blocked URL, navigation timeout, Chromium missing, or oversized image → `{error, is_error}`. Invalid API key → platform 401.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/shot.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://shot`


---