# Opencage — how to use (mcp.ai)

Connect your Opencage account and use 7 tools for developer tools straight from your AI agent. Connect with your own API key. OpenCage Geocoder provides a simple API for forward and reverse geocoding using open data sources.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_opencage?ms=1787293500000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `opencage_geocode_forward`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/opencage`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/opencage/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/opencage/geocode/forward` — Tool to convert a human-readable address into geographic coordinates. Use when you need to retrieve latitude and longitude from an address.
  - body: { q: string, abbrv?: integer, limit?: integer, bounds?: string, pretty?: boolean, language?: string, proximity?: string, add_request?: integer, countrycode?: string, min_confidence?: integer, no_annotations?: boolean }
- `POST https://api.mcp.ai/api/opencage/geocode/geojson` — Geocode addresses or coordinates and return results in GeoJSON FeatureCollection format. Use this tool when you need: - Geographic data in standard GeoJSON format for mapping applications - Forward ge
  - body: { q: string, abbrv?: integer, limit?: integer, bounds?: string, pretty?: boolean, language?: string, roadinfo?: boolean, proximity?: string, add_request?: boolean, countrycode?: string, address_only?: boolean, min_confidence?: integer, no_annotations?: boolean }
- `POST https://api.mcp.ai/api/opencage/geocode/geojsonp` — Geocode an address and return results wrapped in a JavaScript callback function (JSONP format). Use this tool when you need geocoding results that can be directly consumed by JavaScript through a call
  - body: { q: string, abbrv?: integer, limit?: integer, bounds?: string, pretty?: integer, callback: string, language?: string, no_dedupe?: integer, no_record?: integer, proximity?: string, add_request?: integer, countrycode?: string, min_confidence?: integer, no_annotations?: integer }
- `POST https://api.mcp.ai/api/opencage/geocode/google/v3/json` — Tool to perform forward geocoding and return results in Google Geocoding API v3 compatible JSON format. Use when you need Google v3 compatible output for legacy integrations. Note: This is a legacy fo
  - body: { q: string, abbrv?: integer, limit?: integer, bounds?: string, pretty?: integer, language?: string, roadinfo?: integer, no_dedupe?: integer, no_record?: integer, proximity?: string, add_request?: integer, countrycode?: string, address_only?: integer, no_annotations?: integer }
- `POST https://api.mcp.ai/api/opencage/geocode/reverse` — Tool to convert coordinates to a human-readable address. Use when you have latitude and longitude and need a readable location.
  - body: { q: string, abbrv?: integer, limit?: integer, pretty?: integer, language?: string, roadinfo?: integer, add_request?: integer, countrycode?: string, normalizecity?: integer, min_confidence?: integer, no_annotations?: integer }
- `POST https://api.mcp.ai/api/opencage/geocode/xml` — Geocode a location query and return results in XML format. Supports both forward geocoding (address to coordinates) and reverse geocoding (coordinates to address). Use this when you need XML-formatted
  - body: { q: string, abbrv?: integer, limit?: integer, pretty?: integer, language?: string, roadinfo?: integer, no_dedupe?: integer, add_request?: integer, countrycode?: string, min_confidence?: integer, no_annotations?: integer }
- `POST https://api.mcp.ai/api/opencage/ping/opencage` — Tool to check API health and connectivity. Returns 'pong' if the API is reachable. Use when you need to verify that the OpenCage API is accessible and operational.

## Example prompts
- "What can I do in Opencage?"
- "Show me a summary of my Opencage account"

## More
- Page: https://mcp.ai/opencage
- Agent spec (llms.txt): https://mcp.ai/opencage/llms.txt
- Postman collection: https://mcp.ai/opencage/postman.json