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, ChatGPT, Grok, Cursor, and other MCP-compatible clients.

Authentication options

Kakiyo’s MCP server supports two authentication paths:

OAuth (recommended)

Default for Claude, ChatGPT, Grok, Cursor, Claude Code, and any other MCP client that supports remote HTTP. Users log in on Kakiyo, select a team, and approve the connector. No API key is pasted. Manage and revoke these connections from Developer → MCP.

API key header (optional)

Fallback for clients that cannot run OAuth. Uses a 40-character team-scoped API key in the Authorization header.

Quick Start

1. Open Developer → MCP

In the Kakiyo Dashboard, go to Developer → MCP. Copy the MCP server URL (https://api.kakiyo.com/mcp). Most clients, including Claude, ChatGPT, Grok, Cursor, and Claude Code, connect over OAuth and do not need an API key.

2. Configure Your MCP Client

Choose your MCP client and add the configuration:

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

In Kakiyo, open Developer → MCP and copy the server URL
Go to claude.ai → Customize → 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 MCP connector consent screen — Kakiyo OAuth consent screen for an MCP connector

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.

ChatGPT connects over OAuth (Client ID Metadata Documents, with Dynamic Client Registration as a fallback). No API key is pasted.

In Kakiyo, open Developer → MCP and copy the server URL
In ChatGPT, open Settings → Connectors
Turn on Developer mode
Add a remote MCP server and paste https://api.kakiyo.com/mcp

ChatGPT will send you through the same Kakiyo consent screen to pick a team and approve access.

Custom MCP connectors in ChatGPT require Developer mode. Without it, only directory connectors appear.

Grok connects over OAuth using Dynamic Client Registration. No API key is pasted.

In Kakiyo, open Developer → MCP and copy the server URL
Go to grok.com/connectors
Choose New Connector → Custom
Paste https://api.kakiyo.com/mcp

Grok will open Kakiyo’s consent screen. Approve the selected team to finish.

Add Kakiyo as a remote HTTP server. Do not pass an Authorization header — that skips OAuth.

claude mcp add --scope user --transport http kakiyo https://api.kakiyo.com/mcp

Then authenticate:

In Claude Code, run /mcp and choose Authenticate
Or run claude mcp login kakiyo
Kakiyo opens the consent screen so you can pick a team

If you already added Kakiyo with --header "Authorization:Bearer …", remove that server and add it again without the header so OAuth can run.

Cursor connects over the same OAuth flow. Add the URL only — no headers.

Open Settings → Tools & MCP
Add a remote MCP server with https://api.kakiyo.com/mcp
Press Connect and approve the Kakiyo team on the consent screen

Or add it in .cursor/mcp.json:

{
  "mcpServers": {
    "kakiyo": {
      "url": "https://api.kakiyo.com/mcp"
    }
  }
}

If your OpenCode version supports MCP OAuth, add the URL without headers and complete the Kakiyo consent screen. Otherwise use an API key:

{
  "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.

Paste https://api.kakiyo.com/mcp as a remote Streamable HTTP server. The client should start OAuth when you connect.

Setting	Value
URL	`https://api.kakiyo.com/mcp`
Transport	Streamable HTTP
Auth	OAuth 2.1 (recommended). Optional: `Authorization: Bearer YOUR_API_KEY` if the client cannot run OAuth
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:

“Find me 20 heads of growth at B2B SaaS companies in Germany and add the best ones to my DACH campaign”
“Show me all my running agents”
“How many AI credits do we have left?”
“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”

Find leads from your AI assistant

Your AI assistant can search for new people to contact, show you who matches, and send the people you pick straight into a campaign, all from the chat. It uses the same Lead Finder as the dashboard, so every search started from your assistant also appears under Searches in Kakiyo.

Finding leads over MCP is available to workspaces on an active trial or paid plan. Other workspaces get a message with a link to Billing.

How it works

Describe who you want

Ask in plain language, for example “Find CTOs at fintech startups in London with 20 to 200 employees”. Your assistant turns this into one precise search and saves it in Kakiyo.

Get matches from Kakiyo's database

Within a few seconds you see a ranked list: name, title, company, location, a match strength (strong or possible) and a short reason why each person fits. Contact details such as email or phone are never shown here.

More results from LinkedIn and the web (automatic)

If the database has fewer than 10 strong matches, Kakiyo also searches LinkedIn and the web in the background. This usually takes one to two minutes, and your assistant brings the extra people in as they are verified.

Pick and send

Tell your assistant who to keep, or say “add the top 30”, and which campaign to use. The assistant confirms with you first, because the campaign’s LinkedIn profile will start contacting these people.

Follow the import

Your assistant reports how many people were added and how many were skipped, for example people the campaign already contacts or people on your Do Not Contact list.

Tips for better results

Be specific. Name the role, seniority, industry, location and company size or stage. “VPs of Sales at B2B SaaS companies in the Nordics with 50 to 500 employees” works far better than “sales SaaS Nordics”.
Mention your campaign. People that campaign’s LinkedIn profile is already talking to are left out automatically.
Refine instead of starting over. “Only companies above 100 people” updates the same search and doesn’t use up a new one.
Ask for more. “Show me the next ones” pages through the same search for free.
Continue in the dashboard. Every search started in chat is under Searches in Kakiyo, where you can review it or send more people later.

Daily limits

To keep searching fast and fair for everyone, lead searches over MCP have daily limits per workspace. The limits use a rolling 24-hour window: each search frees up again exactly 24 hours after you made it.

What	Limit per 24 hours
New searches	20
Refining an existing search (changing its description)	20
Searches that also look on LinkedIn and the web	10

These never count toward a limit:

Asking for the same search again, or for the next page of results
Checking on a search’s progress
Adding people to a campaign
Searches you run in the Kakiyo dashboard

When a limit is reached, your assistant tells you when the next search frees up. If the LinkedIn and web limit is reached, you still get the matches from Kakiyo’s database. You can keep working in the dashboard at any time.

Lead Finder tools (3 tools)

Tool	Description
`find_leads`	Search for people from a plain-language description, refine a search, or get the next page. Returns ranked matches, starts the LinkedIn and web search when needed, and shows how many searches you have left today
`get_lead_search`	Read-only. Collects the extra LinkedIn and web results as they arrive, and follows the import after you send people to a campaign. Waits on the server for up to 25 seconds per call
`add_leads_to_campaign`	Sends the people you picked (or the top N matches) from a search into a campaign. People already contacted by that campaign and people on your Do Not Contact list are skipped. A search can be sent once; start a new search for different people

Available Tools (52)

The MCP server provides 52 tools organized by category. The three Lead Finder tools are described above.

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 (total prospects, left to invite, 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 (10 tools)

Manage leads and conversations. To find new people to contact, use the Lead Finder tools.

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. Optional `customData` (max 3000 chars) is saved on the conversation and available in prompts as `{{customData}}`
`add_prospects_batch`	Add multiple prospects at once. Each prospect may include `customData` (max 3000 chars) for per-conversation prompt context
`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
`update_prospect_custom_data`	Update or clear `customData` on an existing conversation (`{{customData}}` in prompts; max 3000 chars; empty string clears)

Use customData for freeform outreach context unique to that lead — for example the intent signal, post they engaged with, or research note that explains why you are contacting them now. The agent injects it into openers, replies, and follow-ups whenever the prompt includes {{customData}}.

Products (1 tool)

View products/services for campaigns.

Tool	Description
`list_products`	List all products available for outreach

Prompts (3 tools)

Read and patch AI message templates.

Tool	Description
`list_prompts`	List prompt templates (id, name, type, model only — no section text)
`get_prompt`	Get one prompt as sections (`context`, `firstMessage`, `followUps` or `comment`) plus update guidelines. Call this before `update_prompt`
`update_prompt`	Patch those sections. Omitted fields stay stored. `followUps` replaces the whole array (max 3; `delay` is 1-30 days after the previous message). A 4th follow-up is rejected

MCP agents should not send a raw prompt JSON blob. Patch context, firstMessage, or followUps separately. The API assembles and validates the stored JSON. To change one follow-up delay, copy the full followUps array from get_prompt first.

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

AI credits (4 tools)

Read-only wallet and usage for the connected team. These tools cannot buy credits, change plans, or export CSVs. Agency-client workspaces do not receive the wallet balance.

Tool	Description
`get_credits`	Remaining included, purchased, reserved, and available credits
`get_credit_usage`	Usage overview for a date range (default last 30 days, maximum 90 days)
`list_credit_requests`	Paginated detailed usage (50 per page)
`get_credit_request`	One request plus generation attempts

Credit tools report the same customer ledger the dashboard Usage page uses. They never expose Stripe IDs or payment methods.

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

Finding and Adding Leads

You: Find heads of growth at Series A B2B SaaS companies in Germany
     for my DACH Growth campaign

Claude: [Calls list_campaigns, then find_leads with the campaign]

I found 25 strong and possible matches in Kakiyo's database. Here are the top ones:

| Name          | Title          | Company   | Location | Why they match                  |
|---------------|----------------|-----------|----------|---------------------------------|
| Lena Hoffmann | Head of Growth | Finlytics | Berlin   | Leads growth at a Series A SaaS |
| ...           |                |           |          |                                 |

I'm also searching LinkedIn and the web for more.

[Calls get_lead_search]

7 more people found. Which ones should I add to DACH Growth?

You: Add all the strong ones.

Claude: [Calls add_leads_to_campaign, then get_lead_search]

Done: 14 people added to DACH Growth, 2 skipped because the campaign
already contacts them. You can also see this search under Searches in Kakiyo.

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.

You: Add https://linkedin.com/in/sarahchen to campaign camp_123 with context that she commented on our AI outbound post yesterday

Claude: I'll add Sarah with that customData so the agent can reference it in outreach.

[Calls add_prospect with campaignId, linkedinUrl, and customData]

Done. customData is saved on the conversation and available in prompts as {{customData}} (max 3000 characters).

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?

Manage access

OAuth connections are listed on Developer → MCP in the dashboard. Each row shows the client (Claude, ChatGPT, Grok, Cursor, or a generic MCP client), the granted scopes (mcp:read, mcp:write), and the team it can access. Revoking a connection deletes that client’s refresh tokens for the workspace. The client must approve Kakiyo again to reconnect. One-hour access tokens expire on their own. API-key clients are managed from Developer → API Keys, not from the MCP connections list.

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)
API key (Bearer header)

Custom connectors use the standard MCP OAuth flow. When a client 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 remain available for clients that cannot run OAuth. If a client supports both, prefer OAuth and omit the Authorization header.

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:

Rate limits are per-team, not per-key
Lead Finder tools also have daily limits per workspace (rolling 24 hours)

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

How do I disconnect an MCP client?

Open Developer → MCP in the Kakiyo dashboard and revoke the connected session. Clients using an API key are disconnected by deleting that key under Developer → API Keys.

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

Check that you’re using https://api.kakiyo.com/mcp with Streamable HTTP
For OAuth clients (Cursor, Claude Code, Claude, ChatGPT, Grok), add the URL without an Authorization header and complete the Kakiyo consent screen
If you chose the API-key path, verify the key is 40 characters and prefixed with Bearer

Authentication failed

For OAuth: revoke and reconnect from Developer → MCP, and confirm you approved the correct team
For API keys: the key is team-specific, 40 characters, and must be prefixed with Bearer
Generate a new key from the dashboard if you are on the header path and issues persist

Lead search says subscription required

Finding leads over MCP needs an active trial or paid plan. Start a trial or reactivate your subscription from Billing in the dashboard, then ask again.

Lead search says the daily limit was reached

Your workspace used its MCP searches for the last 24 hours. The message says when the next one frees up.
You can still refine or page through searches you already made, follow imports, and use the Lead Finder in the dashboard without limits.

My assistant can't add leads to a campaign

Make sure the campaign has a LinkedIn profile assigned and that the profile isn’t restricted.
A search can be sent to a campaign once. Ask your assistant to start a new search for different people.
If you changed the search after seeing the results, ask your assistant to show the results again and pick from the new list.

Tool not found

The MCP server has 52 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 (recommended)

API key header (optional)

​Quick Start

​1. Open Developer → MCP

​2. Configure Your MCP Client

​3. Start Using Natural Language

​Find leads from your AI assistant

​How it works

​Tips for better results

​Daily limits

​Lead Finder tools (3 tools)

​Available Tools (52)

​Agents (5 tools)

​Campaigns (6 tools)

​Prospects (10 tools)

​Products (1 tool)

​Prompts (3 tools)

​Analytics (2 tools)

​AI credits (4 tools)

​Models (1 tool)

​Webhooks (5 tools)

​Do Not Contact (4 tools)

​Workspaces - Agency (7 tools)

​Authentication (1 tool)

​Example Conversations

​Finding and Adding Leads

​Monitoring Performance

​Managing Prospects

​Agency Workflow

​Manage access

​Technical Details

​Endpoint

​Authentication

​Transport

​Rate Limits

​Error Handling

​Troubleshooting

​Need Help?

API Reference

Dashboard

What is MCP?

Authentication options

Quick Start

1. Open Developer → MCP

2. Configure Your MCP Client

3. Start Using Natural Language

Find leads from your AI assistant

How it works

Tips for better results

Daily limits

Lead Finder tools (3 tools)

Available Tools (52)

Agents (5 tools)

Campaigns (6 tools)

Prospects (10 tools)

Products (1 tool)

Prompts (3 tools)

Analytics (2 tools)

AI credits (4 tools)

Models (1 tool)

Webhooks (5 tools)

Do Not Contact (4 tools)

Workspaces - Agency (7 tools)

Authentication (1 tool)

Example Conversations

Finding and Adding Leads

Monitoring Performance

Managing Prospects

Agency Workflow

Manage access

Technical Details

Endpoint

Authentication

Transport

Rate Limits

Error Handling

Troubleshooting

Need Help?