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:

“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”

Available Tools (49)

The MCP server provides 49 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 (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.

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

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

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

Tool not found

The MCP server has 49 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

​Available Tools (49)

​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

​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

Available Tools (49)

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

Monitoring Performance

Managing Prospects

Agency Workflow

Manage access

Technical Details

Endpoint

Authentication

Transport

Rate Limits

Error Handling

Troubleshooting

Need Help?