MCP Server - Kakiyo

Experimental Feature - The MCP Server is currently in beta. APIs and functionality may change.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with external tools and services. Kakiyo’s MCP server enables you to control your LinkedIn automation using natural language through AI assistants like Claude, Cursor, Windsurf, and other MCP-compatible clients.

Authentication options

Kakiyo’s MCP server supports two authentication paths:

OAuth (Claude custom connectors)

Best for claude.ai, Claude Desktop, and Claude mobile. Users log in on Kakiyo, select a team, and approve the connector. No API key is pasted anywhere.

API key header (Bearer)

Best for Claude Code CLI, Cursor, OpenCode, and any other MCP client that supports custom HTTP headers. Uses a 40-character team-scoped API key.

Quick Start

1. Get Your API Key (for header-based clients)

Skip this step if you only plan to use the Claude custom connector OAuth flow.

Generate an API key from your Kakiyo Dashboard:

Go to Settings → API Keys
Click Create API Key
Copy your 40-character API key

2. Configure Your MCP Client

Choose your MCP client and add the configuration:

Claude.ai (Web & Desktop)
Claude Code (CLI)
OpenCode
Cursor
Other Clients

Use Custom Connectors in the Claude web or desktop interface. No API key is required — Kakiyo uses OAuth.

Go to claude.ai → Settings → Connectors
Click Add custom connector
Enter the URL: https://api.kakiyo.com/mcp
Click Add, then Connect

Claude will open a secure OAuth flow on app.kakiyo.com. You’ll log in (if needed), choose the team Claude should access, and approve the connection.

Kakiyo x Claude MCP connector consent screen

Custom Connectors require a Claude Pro, Max, Team, or Enterprise subscription.

Claude custom connectors do not support pasting a raw API key in the connector dialog. Use the OAuth flow above for claude.ai/Claude Desktop, or use the Claude Code, Cursor, or OpenCode tabs for header-based API-key setups.

Use the CLI command to add Kakiyo MCP:

claude mcp add kakiyo --scope user --transport http https://api.kakiyo.com/mcp --header "Authorization:Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your 40-character API key from the dashboard.

Edit your OpenCode config file at ~/.config/opencode/opencode.json:

{
  "mcp": {
    "kakiyo": {
      "type": "remote",
      "url": "https://api.kakiyo.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "enabled": true
    }
  }
}

After saving, restart OpenCode to load the MCP server.

Add to your Cursor MCP settings (.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "kakiyo": {
      "url": "https://api.kakiyo.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For other MCP-compatible clients, use these connection details:

Setting	Value
URL	`https://api.kakiyo.com/mcp`
Transport	Streamable HTTP
Auth Header	`Authorization: Bearer YOUR_API_KEY`
Method	POST

Refer to your client’s documentation for the exact configuration format.

3. Start Using Natural Language

Once connected, you can control Kakiyo using natural language:

“Show me all my running agents”
“How is my Tech Founders campaign performing?”
“Pause the outreach to john@example.com”
“List all prospects who replied this week”
“Create a new workspace for Acme Corp”

Available Tools (42)

The MCP server provides 42 tools organized by category:

Agents (5 tools)

Manage your LinkedIn automation agents.

Tool	Description
`list_agents`	List all agents with status, working hours, and configuration
`get_agent`	Get detailed info about a specific agent
`update_agent`	Modify working hours, daily limits, or behavior settings
`pause_agent`	Temporarily stop an agent from working
`resume_agent`	Restart a paused agent

Agent creation and setup require the dashboard for security (credentials handling).

Campaigns (6 tools)

Create and manage outreach campaigns.

Tool	Description
`list_campaigns`	List all campaigns with status and prospect counts
`get_campaign_stats`	Get performance metrics (responses, qualified leads, etc.)
`create_campaign`	Create a new campaign with product, prompt, and agent
`update_campaign`	Modify campaign name or variables
`pause_campaign`	Stop a campaign from sending messages
`resume_campaign`	Restart a paused campaign

Prospects (9 tools)

Manage leads and conversations.

Tool	Description
`list_prospects`	List prospects with basic filtering
`get_prospect`	Get full prospect details and conversation history
`add_prospect`	Add a single LinkedIn profile to a campaign
`add_prospects_batch`	Add multiple prospects at once
`search_prospects`	Advanced search with status, date, and campaign filters
`list_campaign_prospects`	List campaign prospects with pagination and filters like `status=4` for replies
`pause_prospect`	Pause outreach to a specific person
`resume_prospect`	Resume a paused conversation
`qualify_prospect`	Mark a prospect as qualified

Products (1 tool)

View products/services for campaigns.

Tool	Description
`list_products`	List all products available for outreach

Prompts (1 tool)

View AI message templates.

Tool	Description
`list_prompts`	List all prompt templates

Analytics (2 tools)

Monitor performance and metrics.

Tool	Description
`get_analytics_overview`	Team-wide metrics across all campaigns
`get_campaign_analytics`	Detailed metrics for a specific campaign

Models (1 tool)

View available AI models.

Tool	Description
`list_models`	List AI models available for message generation

Webhooks (5 tools)

Configure event notifications.

Tool	Description
`list_webhooks`	List configured webhooks
`create_webhook`	Set up a new webhook for event notifications
`update_webhook`	Modify webhook URL, events, or status
`delete_webhook`	Remove a webhook
`list_webhook_events`	List available event types

Do Not Contact (4 tools)

Manage your blocklist.

Tool	Description
`list_dnc`	List all blocked LinkedIn URLs
`add_dnc`	Block a profile from all campaigns
`remove_dnc`	Unblock a profile
`check_dnc`	Check if a URL is blocked

Workspaces - Agency (7 tools)

Agency Plan Required - Workspace tools are only available on Agency plans.

Manage client workspaces for agencies.

Tool	Description
`list_workspaces`	List all client workspaces
`create_workspace`	Create a new client workspace
`delete_workspace`	Delete a workspace (cascading cleanup)
`invite_client`	Invite a client user via email
`remove_client`	Remove a client from workspace
`assign_agent_to_workspace`	Assign an agent to a client workspace
`unassign_agent_from_workspace`	Remove agent from workspace

Authentication (1 tool)

Verify your connection.

Tool	Description
`verify_api_key`	Check if API key is valid

Example Conversations

Monitoring Performance

You: How are my campaigns doing?

Claude: I'll check your campaign performance.

[Calls get_analytics_overview]

Here's your outreach performance summary:
- Total Prospects: 1,247
- Messages Sent: 3,891
- Response Rate: 23.4%
- Qualified Leads: 89
- Active Campaigns: 4

Managing Prospects

You: Find all prospects who replied but aren't qualified yet

Claude: I'll search for replied prospects.

[Calls search_prospects with status="replied"]

Found 34 prospects who replied:
1. Sarah Chen (VP Marketing, TechCorp) - replied 2 days ago
2. Mike Johnson (CEO, StartupXYZ) - replied yesterday
...

Would you like me to qualify any of these?

For campaign-specific replied prospects, use list_campaign_prospects with status=4 and limit=100.

Agency Workflow

You: Set up a new client workspace for Acme Corp and assign Agent-1 to it

Claude: I'll create the workspace and assign the agent.

[Calls create_workspace with name="Acme Corp"]
[Calls assign_agent_to_workspace]

Done! Created workspace "Acme Corp" and assigned Agent-1.
The agent's campaigns will now be visible to Acme Corp clients.

Would you like me to invite a client user?

Technical Details

Endpoint

POST https://api.kakiyo.com/mcp

Authentication

Kakiyo’s MCP server accepts two authentication methods on the same /mcp endpoint:

OAuth 2.1 (recommended for Claude)
API key (Bearer header)

Claude custom connectors use the standard MCP OAuth flow. When Claude calls /mcp without a valid token, Kakiyo responds with:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
                         resource_metadata="https://api.kakiyo.com/.well-known/oauth-protected-resource/mcp",
                         scope="mcp:read mcp:write"

Kakiyo exposes the standard MCP/OAuth metadata endpoints:

Endpoint	Purpose
`GET /.well-known/oauth-protected-resource/mcp`	Protected resource metadata (RFC 9728)
`GET /.well-known/oauth-authorization-server`	Authorization server metadata (RFC 8414)
`GET /mcp/oauth/authorize`	Authorization endpoint (redirects to the Kakiyo consent screen)
`POST /mcp/oauth/token`	Token endpoint (authorization_code + refresh_token grants)

Kakiyo’s OAuth implementation supports:

OAuth 2.1 Authorization Code grant with PKCE (S256)
Client ID Metadata Documents (CIMD) — no manual client registration required
Resource Indicators (RFC 8707) targeting https://api.kakiyo.com/mcp
Refresh tokens with rotation
Team-scoped access tokens (approval binds the connector to one Kakiyo team)

Legacy and programmatic clients can authenticate with a 40-character team-scoped API key:

Authorization: Bearer {your_40_char_api_key}

API keys continue to work for Claude Code CLI, Cursor, OpenCode, and any other MCP client that allows custom HTTP headers.

Transport

The MCP server uses Streamable HTTP transport, which is stateless and compatible with most MCP clients.

Rate Limits

MCP requests follow the same rate limits as the REST API:

Each tool call consumes 1 API credit
Rate limits are per-team, not per-key

Error Handling

Tool errors are returned in MCP format:

{
  "content": [{
    "type": "text",
    "text": "{\"error\": \"campaign_not_found\", \"message\": \"Campaign does not exist\"}"
  }],
  "isError": true
}

Troubleshooting

Claude says 'Couldn't reach the MCP server'

Confirm https://api.kakiyo.com/mcp is reachable and returns 401 with a WWW-Authenticate header
Remove the existing custom connector in Claude and re-add it using the same URL
Make sure you’re not trying to paste a raw API key in the Claude custom connector dialog — use the OAuth flow for claude.ai/Claude Desktop

Claude OAuth flow opens but approval fails

Sign in to app.kakiyo.com first, then retry the Claude connector flow
Make sure your user account has access to at least one Kakiyo team
Approval binds the connector to the team selected on the consent screen; switching teams later requires reconnecting

Connection refused or timeout (non-Claude clients)

Verify your API key is correct (40 characters)
Check that you’re using https://api.kakiyo.com/mcp
Ensure your MCP client supports Streamable HTTP transport

Authentication failed

API keys are team-specific — ensure you’re using the right key
Keys must be prefixed with Bearer in the Authorization header
Generate a new key from the dashboard if issues persist

Tool not found

The MCP server has 42 tools — some operations (like agent creation) require the dashboard
Use verify_api_key to confirm your connection is working

Agency tools not working

Workspace tools require an Agency plan
Verify your team is on the correct plan in the dashboard

Need Help?

API Reference

Full REST API documentation

Dashboard

Manage your account and API keys

​What is MCP?

​Authentication options

OAuth (Claude custom connectors)

API key header (Bearer)

​Quick Start

​1. Get Your API Key (for header-based clients)

​2. Configure Your MCP Client

​3. Start Using Natural Language

​Available Tools (42)

​Agents (5 tools)

​Campaigns (6 tools)

​Prospects (9 tools)

​Products (1 tool)

​Prompts (1 tool)

​Analytics (2 tools)

​Models (1 tool)

​Webhooks (5 tools)

​Do Not Contact (4 tools)

​Workspaces - Agency (7 tools)

​Authentication (1 tool)

​Example Conversations

​Monitoring Performance

​Managing Prospects

​Agency Workflow

​Technical Details

​Endpoint

​Authentication

​Transport

​Rate Limits

​Error Handling

​Troubleshooting

​Need Help?

API Reference

Dashboard

What is MCP?

Authentication options

Quick Start

1. Get Your API Key (for header-based clients)

2. Configure Your MCP Client

3. Start Using Natural Language

Available Tools (42)

Agents (5 tools)

Campaigns (6 tools)

Prospects (9 tools)

Products (1 tool)

Prompts (1 tool)

Analytics (2 tools)

Models (1 tool)

Webhooks (5 tools)

Do Not Contact (4 tools)

Workspaces - Agency (7 tools)

Authentication (1 tool)

Example Conversations

Monitoring Performance

Managing Prospects

Agency Workflow

Technical Details

Endpoint

Authentication

Transport

Rate Limits

Error Handling

Troubleshooting

Need Help?