Skip to content

Remove false claims about HTTP/REST endpoints #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bokelley merged 2 commits into from
Dec 5, 2025
Merged

Remove false claims about HTTP/REST endpoints #36

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
78625e1
Remove false claims about HTTP/REST endpoints
bokelley Dec 5, 2025
e52f059
Fix broken link to ADCP spec docs
bokelley Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 26 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,31 @@ The AdCP Creative Agent is a stateless service that:
- Provides complete specifications for standard IAB creative formats (video, display, audio, native, DOOH)
- Generates live previews from creative manifests using AI (Gemini)
- Stores preview HTML in Tigris (Fly.io's S3-compatible global storage)
- Supports both local development (stdio) and production deployment (HTTP)
- Supports both local development (stdio) and production deployment (streamable-http)

## Architecture

```
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
│ MCP Clients │ │ ADCP HTTP Clients │
│ (Claude, Agents) │ │ (TypeScript, Python) │
└────────┬─────────────────────────┘ └────────┬─────────────────────────┘
│ │
│ MCP Protocol │ HTTP JSON
│ (stdio or HTTP at /mcp) │ (at /adcp/*)
│ │
┌────────▼───────────────────────────────────────▼────────────────────────┐
│ AdCP Creative Agent (Combined Server) │
┌──────────────────────────────────┐
│ MCP Clients │
│ (Claude, Agents, MCP Libraries) │
└────────┬─────────────────────────┘
│
│ MCP Protocol
│ (stdio locally, streamable-http in production)
│
┌────────▼─────────────────────────────────────────────────────────────────┐
│ AdCP Creative Agent (MCP Server) │
│ │
│ /mcp - MCP Protocol Endpoint /adcp - ADCP HTTP Endpoints │
│ (JSON-RPC wrapped responses) (Direct ADCP JSON responses) │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ list_creative_formats - Returns all standard format specs │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ build_creative - AI-powered creative generation (Gemini) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ preview_creative - Renders creative to HTML, uploads to Tigris │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ list_creative_formats - Returns all standard format specs │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ build_creative - AI-powered creative generation (Gemini) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ preview_creative - Renders creative to HTML, uploads to Tigris │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────┬───────────────────────────────────────┘
│
│ S3 API
Expand All @@ -48,24 +45,14 @@ The AdCP Creative Agent is a stateless service that:
└──────────────────────────────────────────────────────────────────────────┘
```

## Endpoints

The server provides two protocols for accessing the same tools:
## Protocol

### MCP Endpoint (`/mcp`)
For MCP clients (like Claude Desktop, MCP client libraries):
- Follows MCP JSON-RPC protocol specification
- Responses wrapped in `{"result": {"content": [{"type": "text", "text": "..."}]}}`
- Use with MCP client libraries or Claude Desktop integration
This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) using FastMCP:

### ADCP HTTP Endpoints (`/adcp/*`)
For direct HTTP clients that expect unwrapped ADCP responses:
- `GET /adcp/list-creative-formats` - List all available formats
- `POST /adcp/list-creative-formats` - List formats with filters (JSON body)
- `POST /adcp/preview-creative` - Generate creative preview
- `POST /adcp/build-creative` - AI-powered creative generation
- **Local development**: stdio transport (default)
- **Production (Fly.io)**: streamable-http transport on port 8080

Returns clean ADCP JSON responses without MCP protocol wrapping.
Use any MCP client library to connect. For Claude Desktop integration, see the configuration below.

## Quick Start

Expand Down Expand Up @@ -515,4 +502,4 @@ Apache 2.0 License - see LICENSE file

## Spec Reference

Format specifications from [AdCP Media Buy Protocol](https://adcontextprotocol.org/docs/media-buy/specification)
Format specifications from [AdCP Media Buy Protocol](https://docs.adcontextprotocol.org/docs/media-buy/overview)