---
name: smad-api-and-mcp
description: Reference for connecting to the Social Media Agency Directory MCP server and REST API (tools, endpoints, filters, error and rate-limit behaviour). Use when writing code or configuring an MCP client that needs agency data.
---

# Social Media Agency Directory: MCP and REST reference

Everything is free, read-only and unauthenticated.

## MCP server

- URL: `https://socialmediaagencydirectory.com/mcp` (MCP Streamable HTTP, stateless, JSON responses, no session id)
- Server card: https://socialmediaagencydirectory.com/.well-known/mcp/server-card.json
- Claude Code: `claude mcp add --transport http smad https://socialmediaagencydirectory.com/mcp`
- Generic JSON config: `{ "mcpServers": { "smad": { "type": "http", "url": "https://socialmediaagencydirectory.com/mcp" } } }`

Tools: `search_agencies`, `get_agency`, `list_locations`, `list_services`, `top_agencies`, `directory_stats`. There is also a `find_agency` prompt.

`search_agencies` arguments (all optional): `query`, `country`, `city`, `service`, `platform`, `max_budget_usd`, `verified_only`, `limit` (1 to 25, default 10), `offset`.

## REST API

OpenAPI 3.1: https://socialmediaagencydirectory.com/api/v1/openapi.json (API catalog: https://socialmediaagencydirectory.com/.well-known/api-catalog)

- `GET /api/v1/agencies` (same filters as `search_agencies`; `q` is an alias of `query`)
- `GET /api/v1/agencies/{slug}`
- `GET /api/v1/locations?country=`
- `GET /api/v1/services`
- `GET /api/v1/top-agencies?city=`
- `GET /api/v1/stats`

Errors look like `{ "error": { "code", "message" } }`. Bad values return HTTP 400, unknown agencies 404.

## Limits and terms

- 60 requests per minute and 2,000 per day per IP. Over the limit: HTTP 429 with `Retry-After` (MCP: JSON-RPC error -32029). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
- Attribute "Social Media Agency Directory" and link the agency profile when you show results.
- No bulk download to republish or resell, no unsolicited bulk email. Data is provided as is.
- Only information already public on each agency's profile page is exposed. No contact emails or private data.

Full documentation: https://socialmediaagencydirectory.com/for-ai-agents
