MCP Tools API Reference

Complete technical reference for all Model Context Protocol (MCP) tools provided by Rampify.

Authentication

All MCP tool calls require authentication via API key:

export RAMPIFY_API_KEY=sk_live_abc123...

See Authentication for details.

get_seo_context

Get comprehensive SEO context for a domain.

Signature

get_seo_context(params: {
  domain: string;
}): Promise<SEOContext>

Parameters

Returns

interface SEOContext {
  domain: string;
  last_crawled_at: string | null;
  total_urls: number;

  indexing_status: {
    indexed: number;
    not_indexed: number;
    blocked: number;
    errors: number;
  };

  recent_issues: Array<{
    id: string;
    type: string;
    severity: 'critical' | 'warning' | 'info';
    title: string;
    url?: string;
    first_detected_at: string;
  }>;

  top_queries?: Array<{
    query: string;
    clicks: number;
    impressions: number;
    ctr: number;
    position: number;
  }>;

  technology?: {
    cms?: string;
    hosting?: string;
    cdn?: string;
  };
}

Example Usage

In Cursor/Claude Code:

Show me the SEO context for example.com

Direct API Call:

curl https://api.rampify.ai/v1/mcp/get-seo-context \
  -H "Authorization: Bearer $RAMPIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Response Example

{
  "domain": "example.com",
  "last_crawled_at": "2025-01-09T10:30:00Z",
  "total_urls": 247,
  "indexing_status": {
    "indexed": 230,
    "not_indexed": 12,
    "blocked": 5,
    "errors": 0
  },
  "recent_issues": [
    {
      "id": "abc123",
      "type": "http_404",
      "severity": "critical",
      "title": "Page not found",
      "url": "https://example.com/old-page",
      "first_detected_at": "2025-01-08T15:20:00Z"
    }
  ],
  "top_queries": [
    {
      "query": "seo tools",
      "clicks": 1234,
      "impressions": 45678,
      "ctr": 2.7,
      "position": 8.5
    }
  ],
  "technology": {
    "cms": "Next.js",
    "hosting": "Vercel",
    "cdn": "Cloudflare"
  }
}

Errors

---

scan_site

Trigger a full site scan to discover new pages and check for issues.

Signature

scan_site(params: {
  domain: string;
  force?: boolean;
}): Promise<ScanResult>

Parameters

Returns

interface ScanResult {
  scan_id: string;
  domain: string;
  status: 'queued' | 'in_progress' | 'completed' | 'failed';
  urls_discovered: number;
  estimated_duration_seconds: number;
  started_at: string;
  completed_at?: string;
  error?: string;
}

Example Usage

In Cursor/Claude Code:

Scan example.com for new pages and issues

Direct API Call:

curl https://api.rampify.ai/v1/mcp/scan-site \
  -H "Authorization: Bearer $RAMPIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "force": false}'

Response Example

{
  "scan_id": "scan_xyz789",
  "domain": "example.com",
  "status": "in_progress",
  "urls_discovered": 247,
  "estimated_duration_seconds": 120,
  "started_at": "2025-01-09T11:00:00Z"
}

Rate Limits

Errors

---

generate_meta

Generate optimized title tags and meta descriptions using AI.

Signature

generate_meta(params: {
  url: string;
  content?: string;
  target_keywords?: string[];
  tone?: 'professional' | 'casual' | 'technical';
}): Promise<MetaTagsResult>

Parameters

Returns

interface MetaTagsResult {
  title: string;
  meta_description: string;
  reasoning: string;
  alternatives?: {
    titles: string[];
    descriptions: string[];
  };
}

Example Usage

In Cursor/Claude Code:

Generate optimized meta tags for my blog post about Next.js SEO

Direct API Call:

curl https://api.rampify.ai/v1/mcp/generate-meta \
  -H "Authorization: Bearer $RAMPIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/nextjs-seo",
    "target_keywords": ["nextjs seo", "react seo"],
    "tone": "technical"
  }'

Response Example

{
  "title": "Next.js SEO Best Practices: Complete Guide for 2025",
  "meta_description": "Learn proven Next.js SEO techniques including metadata, sitemaps, and structured data. Boost your React app's search rankings with our comprehensive guide.",
  "reasoning": "Title includes primary keyword and year for freshness. Description is compelling, under 160 characters, and includes call-to-action.",
  "alternatives": {
    "titles": [
      "Master Next.js SEO: Expert Tips and Techniques",
      "Next.js SEO Optimization: A Developer's Guide"
    ],
    "descriptions": [
      "Optimize your Next.js app for search engines. Step-by-step guide covering metadata, sitemaps, structured data, and more.",
      "Complete Next.js SEO tutorial for developers. Learn how to implement metadata, generate sitemaps, and boost search rankings."
    ]
  }
}

Best Practices

For best results:

• Include page content when available
• Specify 1-3 target keywords max
• Match tone to your brand voice
• Review alternatives for options

Errors

---

check_before_deploy

Run pre-deployment SEO checks on your changes.

Availability: Starter tier and above

Signature

check_before_deploy(params: {
  domain: string;
  changed_files?: string[];
  changed_urls?: string[];
}): Promise<DeploymentCheck>

Parameters

Returns

interface DeploymentCheck {
  status: 'pass' | 'warning' | 'fail';
  checks: Array<{
    type: string;
    status: 'pass' | 'warning' | 'fail';
    message: string;
    affected_urls?: string[];
  }>;
  recommendations: string[];
  safe_to_deploy: boolean;
}

Example Usage

In Cursor/Claude Code:

Check my changes for SEO issues before I deploy

Direct API Call:

curl https://api.rampify.ai/v1/mcp/check-before-deploy \
  -H "Authorization: Bearer $RAMPIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "changed_files": [
      "app/blog/seo-tips/page.tsx",
      "app/about/page.tsx"
    ]
  }'

Response Example

{
  "status": "warning",
  "checks": [
    {
      "type": "meta_tags",
      "status": "pass",
      "message": "All pages have title and description"
    },
    {
      "type": "internal_links",
      "status": "warning",
      "message": "New blog post has no internal links",
      "affected_urls": ["https://example.com/blog/seo-tips"]
    },
    {
      "type": "canonical_tags",
      "status": "pass",
      "message": "Canonical tags properly configured"
    }
  ],
  "recommendations": [
    "Add 2-3 internal links to your new blog post",
    "Consider adding schema markup for Article type"
  ],
  "safe_to_deploy": true
}

Checks Performed

• ✅ Meta tags (title, description)
• ✅ Internal linking
• ✅ Canonical tags
• ✅ Schema.org markup
• ✅ Robots meta tags
• ✅ Open Graph tags
• ✅ XML sitemap updates

Errors

---

suggest_internal_links

Get AI-powered internal linking suggestions.

Availability: Pro tier only

Signature

suggest_internal_links(params: {
  url: string;
  content?: string;
  max_suggestions?: number;
}): Promise<InternalLinkSuggestions>

Parameters

Returns

interface InternalLinkSuggestions {
  suggestions: Array<{
    anchor_text: string;
    target_url: string;
    reasoning: string;
    confidence: number; // 0-1
    location_hint?: string;
  }>;
  total_analyzed: number;
}

Example Usage

In Cursor/Claude Code:

Suggest internal links for my new blog post about Next.js

Direct API Call:

curl https://api.rampify.ai/v1/mcp/suggest-internal-links \
  -H "Authorization: Bearer $RAMPIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/nextjs-seo",
    "max_suggestions": 5
  }'

Response Example

{
  "suggestions": [
    {
      "anchor_text": "Next.js metadata API",
      "target_url": "https://example.com/blog/nextjs-metadata",
      "reasoning": "Highly relevant technical content. Target page has high authority.",
      "confidence": 0.92,
      "location_hint": "Section about metadata configuration"
    },
    {
      "anchor_text": "sitemap generation",
      "target_url": "https://example.com/blog/sitemaps-guide",
      "reasoning": "Contextually relevant. Helps users understand related topic.",
      "confidence": 0.85,
      "location_hint": "Paragraph discussing site discovery"
    }
  ],
  "total_analyzed": 247
}

Suggestion Algorithm

Analyzes:

• Semantic relevance - Content similarity
• Page authority - Traffic and links
• User intent - Query patterns
• Topic clustering - Related content groups

Errors

---

Error Handling

All MCP tools return errors in this format:

interface ErrorResponse {
  error: {
    type: string;
    message: string;
    details?: Record<string, any>;
  };
}

Common Error Types

---

Rate Limits

Rate limits vary by tier and tool:

Per-Tool Limits

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 943
X-RateLimit-Reset: 1673280000

---

Caching

MCP server implements intelligent caching:

Cache duration:

• get_seo_context: 5 minutes
• scan_site: No cache (always fresh)
• generate_meta: 1 hour (per unique input)
• check_before_deploy: No cache
• suggest_internal_links: 30 minutes

Cache headers:

X-Cache-Status: HIT | MISS
X-Cache-Age: 123 (seconds)

---

Next Steps

• View tool examples
• Learn about authentication
• Install MCP server