AI Agents

Connect your AI agents to Typograph and unlock the power of automated document generation, file management, and creative workflows.

The Typograph MCP Server implements the Model Context Protocol — the open standard adopted by Anthropic, OpenAI, and Google for connecting AI to external tools and data.

Production URL: https://mcp.typograph.nl

What AI Agents Can Do

With 55 tools available, your AI agents can:

• Manage content - Create and organize teams, projects, and templates
• Generate documents - Create PDFs, images, and other formats from templates
• Convert files - Transform between file formats
• Collaborate - Share resources, manage permissions, invite users
• Search - Find projects, templates, and resources

Quick Start

Typograph runs the MCP server as a hosted HTTP service at https://mcp.typograph.nl — there is nothing to install locally.

Claude Desktop (and other MCP clients)

Point your MCP client's mcpServers config at the hosted URL:

{
  "mcpServers": {
    "typograph": {
      "url": "https://mcp.typograph.nl/mcp"
    }
  }
}

On the first tool call you'll receive an auth_required response with a browser URL — open it, authorize, and the session is stored.

Direct HTTP (JSON-RPC)

POST https://mcp.typograph.nl/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "team_list",
    "arguments": {}
  }
}

Authentication

The MCP server uses OAuth 2.0 Authorization Code flow with automatic token management.

How Authentication Works

1. First tool call - If no valid token exists, the server returns an auth_required response with an authorization URL
2. User authorization - Open the URL in a browser to authorize the application
3. Automatic token storage - Tokens are securely stored (AES-256-GCM encrypted)
4. Automatic refresh - Tokens are refreshed automatically when expired

Auth Required Response

{
  "type": "auth_required",
  "auth_uri": "https://api.typograph.nl/oauth/authorize?client_id=...",
  "scopes": ["identity:read", "file", "document", "publisher", "converter", "subscription:read", "offline_access"]
}

Required Scopes

Scope	Description
identity:read	User profile access
file	Team, project, and template management
document	Document validation
publisher	PDF and image generation
converter	File format conversion
subscription:read	Subscription and usage info
offline_access	Refresh token support

Available Tools

Account Management

Tool	Description
account_whoami	Get current user profile (ID, email, role, scopes)
account_logout	Revoke access token and log out

Teams

Tool	Description
team_list	List teams with pagination
team_get	Get team details by ID
team_create	Create a new team
team_update	Update team name
team_delete	Soft delete a team
team_restore	Restore a deleted team

Projects

Tool	Description
project_list	List projects in a team
project_list_shared	List projects shared with you
project_get	Get project details
project_create	Create a new project
project_update	Update project name
project_delete	Soft delete a project
project_restore	Restore a deleted project

Templates

Tool	Description
template_list	List templates in a project
template_list_shared	List templates shared with you
template_get	Get template details
template_create	Create a new template
template_update	Update template name
template_touch	Update modification timestamp
template_delete	Soft delete a template
template_restore	Restore a deleted template

Media & Fonts

Tool	Description
media_list	List media assets in a project
media_get_urls	Get presigned download URLs for media
font_list	List fonts in a project
font_update	Update font display name
font_get_urls	Get presigned download URLs for fonts

File Uploads

Tool	Description
upload_list	List upload jobs
upload_create	Create upload job and get presigned URL
upload_process	Start processing an uploaded file

Document Generation (Publisher)

Tool	Description
publisher_job_list	List generation jobs with status
publisher_job_get	Get job details by ID
publisher_job_create	Create a document generation job
publisher_job_files	Get output files from completed job

Example: Generate a PDF

{
  "name": "publisher_job_create",
  "arguments": {
    "template_url": "https://storage.typograph.nl/templates/invoice.json",
    "data_url": "https://your-server.com/data.json",
    "output_format": "pdf"
  }
}

File Conversion (Converter)

Tool	Description
converter_job_list	List conversion jobs
converter_job_get	Get conversion job details
converter_job_create	Create a file conversion job
converter_job_files	Get output files from completed job

Document Validation

Tool	Description
document_validate	Validate a document template against schema

Search

Tool	Description
search	Full-text search across projects, templates, and resources

Example: Search templates

{
  "name": "search",
  "arguments": {
    "query": "invoice",
    "type": "template"
  }
}

Notifications

Tool	Description
notification_list	List user notifications
notification_mark_read	Mark notification as read
notification_mark_unread	Mark notification as unread
notification_mark_all_read	Mark all notifications as read

Invitations & Sharing

Tool	Description
invite_list_resource	List invites for a resource
invite_list_my	List invites sent to you
invite_create	Send an invite to a user
invite_accept	Accept an invitation
invite_decline	Decline an invitation
invite_delete	Delete/revoke an invitation

Access Control

Tool	Description
role_list	List roles for a resource
role_update	Update user/team role
role_delete	Remove user/team from resource

Contacts

Tool	Description
contact_list	List team contacts
contact_create	Add a contact to a team

Favorites & Recent

Tool	Description
favorite_list	List favorite projects/templates
favorite_toggle	Toggle favorite status
recent_templates	List recently viewed templates
recent_searches	List recent search queries

Trash

Tool	Description
trash_list	List deleted items in trash

HTTP Endpoints

Endpoint	Description
POST /mcp	JSON-RPC 2.0 endpoint for tool calls
GET /oauth/authorize	Initiate OAuth authorization
GET /oauth/callback	OAuth callback handler
GET /.well-known/oauth-authorization-server	OAuth server metadata (RFC 8414)
GET /.well-known/oauth-protected-resource	Protected resource metadata (RFC 9728)
GET /health	Health check endpoint

OAuth Discovery

The MCP server implements OAuth 2.0 metadata discovery:

curl https://mcp.typograph.nl/.well-known/oauth-authorization-server

Response:

{
  "issuer": "https://mcp.typograph.nl",
  "authorization_endpoint": "https://api.typograph.nl/oauth/authorize",
  "token_endpoint": "https://api.typograph.nl/oauth/token",
  "scopes_supported": ["identity:read", "file", "document", "publisher", "converter", "subscription:read", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}

Response Format

Success Response

{
  "type": "success",
  "data": {
    "teams": [
      {
        "id": "019b28fb-a11e-7641-a28f-e978f892ec06",
        "name": "Marketing",
        "created_at": "<ISO 8601 timestamp>"
      }
    ]
  },
  "pagination": {
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

Error Response

{
  "type": "error",
  "code": "not_found",
  "message": "Team not found"
}

Auth Required Response

{
  "type": "auth_required",
  "auth_uri": "https://api.typograph.nl/oauth/authorize?...",
  "scopes": ["identity:read", "file", "document", "publisher", "converter", "subscription:read", "offline_access"]
}

Example Workflows

Generate a Document

1. team_list → Get available teams
2. project_list → List projects in team
3. template_list → Find the template
4. publisher_job_create → Create generation job
5. publisher_job_get → Check job status (poll until completed)
6. publisher_job_files → Download generated files

Upload and Use Media

1. upload_create → Get presigned upload URL
2. [Upload file to presigned URL]
3. upload_process → Process the uploaded file
4. media_list → Verify media is available
5. template_update → Reference media in template

Share a Project

1. project_get → Get project details
2. invite_create → Send invite to collaborator
3. role_list → Verify roles assigned

Security

Token Encryption

All refresh tokens are encrypted using AES-256-GCM before storage. Access tokens are kept in memory only.

Session Isolation

Each MCP client connection gets an isolated session. Tokens from one session cannot be accessed by another.

Output Sanitization

Sensitive data (tokens, secrets) is automatically redacted from tool responses.

Configuration

Environment Variables

Variable	Description	Default
OAUTH_CLIENT_ID	OAuth client ID	Required
OAUTH_CLIENT_SECRET	OAuth client secret	Required
OAUTH_REDIRECT_URI	OAuth callback URL	http://localhost:3000/oauth/callback
OAUTH_AUTHORIZE_URL	Authorization endpoint	https://api.typograph.nl/oauth/authorize
OAUTH_TOKEN_URL	Token endpoint	https://api.typograph.nl/oauth/token
OAUTH_SCOPES	Comma-separated scopes	identity:read,file,document,publisher,converter,subscription:read,offline_access
TOKEN_ENCRYPTION_KEY	32+ char encryption key	Required
TYPOGRAPH_API_BASE_URL	API base URL	https://api.typograph.nl
MCP_SERVER_HOST	Server host	0.0.0.0
MCP_SERVER_PORT	Server port	3000

Rate Limits

MCP server requests ultimately hit the Typograph API Gateway, so they're subject to the same tiered rate limits — categorized per endpoint and driven by your organization's subscription. See Rate Limiting.

Best Practices

For AI Agent Developers

1. Handle auth_required responses - Prompt users to authorize when needed
2. Poll job status - Use exponential backoff when checking job completion
3. Use pagination - Large result sets are paginated; iterate through pages
4. Cache team/project IDs - Reduce API calls by caching resource identifiers
5. Check scopes - Verify your client has required scopes before operations

Error Handling

async function callTool(name, args) {
  const response = await mcpClient.callTool(name, args);

  if (response.type === 'auth_required') {
    // Prompt user to open auth_uri in browser
    console.log('Please authorize:', response.auth_uri);
    return;
  }

  if (response.type === 'error') {
    console.error(`Error: ${response.code} - ${response.message}`);
    return;
  }

  return response.data;
}

Standards Compliance

• MCP Protocol: 2024-11-05 specification
• OAuth 2.0: RFC 6749, RFC 7636 (PKCE)
• OAuth Metadata: RFC 8414, RFC 9728
• JSON-RPC: 2.0 specification