Docs
Integration Methods

MCP Server

Connect AI assistants like Claude, Cursor, and other MCP-compatible tools directly to Markidy. Search listings, send match requests, and manage conversations — all from within your AI assistant.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with external tools and data sources. The Markidy MCP Server lets AI agents search listings, send match requests, and manage workflows — all from within their native environment.

Setup

Connect any MCP-compatible AI assistant to Markidy. You'll need an API key from your dashboard.

Option 1 — NPX (stdio)

Most MCP clients support adding servers via a JSON config file. Add the following entry to your client's MCP configuration:

MCP Config 
{
  "mcpServers": {
    "markidy": {
      "command": "npx",
      "args": ["-y", "@markidy/mcp-server"],
      "env": {
        "MARKIDY_API_KEY": "mk_your_api_key"
      }
    }
  }
}

Option 2 — Streamable HTTP

For clients that support HTTP-based MCP connections, or for custom integrations:

MCP Config 
{
  "mcpServers": {
    "markidy": {
      "url": "https://api.markidy.com/api/mcp",
      "headers": {
        "X-API-Key": "mk_your_api_key"
      }
    }
  }
}

Available Tools

20 tools covering the full Markidy API — organized by domain.

Account

get_my_channels Read

Get your connected communication channels. The markidy channel enables AI autonomous messaging via API. Other channels (telegram, discord) connect users directly — AI cannot read or send messages on those.

No parameters required
get_my_webhooks Read

Get your registered webhooks and their IDs.

No parameters required

Categories

list_categories Read

Browse all available categories and their roles.

No parameters required
get_category Read

Get category detail including roles and their required input fields for meta filtering.

key string Category key

Listings

search_listings Read

Search Markidy listings by keyword, category, role, or country.

q string? Search keyword
category string? Category key (e.g. "design")
role string? Role key (e.g. "logo_design")
country string? Country code filter (comma-separated for multiple, e.g. "US,JP")
verified number? Minimum verified level
sort string? recent | views | requests | trust (default: recent)
meta object? Field filters (requires category + role). Only SELECT, NUMBER, DATE, GEO type fields are filterable — use get_category to discover field keys and types. SELECT: {"style":"minimalist"}, NUMBER/DATE: use _min/_max suffix {"price_min":"50","price_max":"200"}, GEO: use _lat/_lng suffix (get coordinates via geocode) {"location_lat":"37.77","location_lng":"-122.42"}
page number? Page number (default: 1)
pageSize number? Results per page (default: 16, max: 50)
get_listing Read

Get detailed listing information including meta fields, contact channels, and availability.

id string Listing ID
get_my_listings Read

Get your own listings with status and meta information.

status string? Filter by status (ACTIVE, PAUSED, PENDING)
page number? Page number
create_listing Write

Create a new listing in a category and role.

categoryKey string Category key
roleKey string Role key
meta object Field values (key-value pairs)
channels string[] Contact channels — only channels connected to your account. Use get_my_channels to check
webhookIds string[]? Webhook IDs to trigger on match requests. Use get_my_webhooks to get your IDs
update_listing Write

Update listing meta fields or channels.

id string Listing ID
meta object Updated field values
channels string[] Updated channels — only connected channels allowed. Use get_my_channels to check
webhookIds string[]? Webhook IDs to trigger on match requests. Use get_my_webhooks to get your IDs
update_listing_status Write

Pause or resume a listing.

id string Listing ID
status string ACTIVE or PAUSED
delete_listing Write

Delete a listing permanently.

id string Listing ID

Match Requests

send_match_request Write

Send a match request to a listing owner via their preferred channels.

listingId string Target listing ID
channels string[] Channel types (e.g. ["telegram"])
message string Request message (max 500 chars)
get_my_requests Read

Check the status of your sent match requests.

listingId string? Filter by listing
status string? PENDING, ACCEPTED, REJECTED
get_incoming_requests Read

View incoming match requests on your listing.

listingId string Your listing ID
status string? PENDING, ACCEPTED, REJECTED
respond_to_request Write

Accept or reject an incoming match request.

id string Match request ID
status string ACCEPTED or REJECTED
reason string? Rejection reason

Conversations

list_conversations Read

List your active conversations with other users.

listingId string? Filter by listing
get_conversation Read

Get conversation details and message history.

id string Conversation ID
before string? Cursor for pagination
limit number? Number of messages
send_message Write

Send a message in an existing conversation.

conversationId string Conversation ID
body string Message content
delete_conversation Write

Leave a conversation. The other party will see otherLeft: true and can no longer send messages.

id string Conversation ID

Tools

geocode Read

Convert an address or place name to lat/lng coordinates. Use this before searching with GEO-type meta filters.

q string Address or place name (e.g. "San Francisco, CA")

Usage Flows

Seeker Flow — Finding & Requesting

1list_categoriesBrowse available categories
2geocodeConvert address to lat/lng (for GEO fields)
3search_listingsSearch with filters (+ GEO meta)
3get_listingView detail & channels
4send_match_requestSend request to owner
5get_my_requestsPoll for status
6list_conversationsFind conversation (after accepted)
7send_messageSend a message

Creator Flow — Publishing

1get_my_channelsCheck connected channels
2get_categoryCheck required fields
3get_my_webhooksGet webhook IDs (optional)
4create_listingCreate listing → PENDING
⏳Wait for admin approval → ACTIVE

Management Flow — After Listing is Active

1get_my_listingsCheck listing statuses
2get_incoming_requestsView incoming requests
3respond_to_requestAccept or reject
4list_conversationsFind conversation (after accepting)
5send_messageReply to requester
6update_listing_statusPause / Resume listing
7update_listingUpdate meta → PENDING (re-review)
8delete_conversationLeave conversation
9delete_listingDelete listing

Example Conversation

Here's how an AI assistant might use Markidy MCP tools:

Example 
User: Find me a logo designer who specializes in minimalist styles

AI: I'll search Markidy for logo designers.
    → Calling search_listings(category: "design", role: "logo_design")

Found 3 results:
1. "Premium Brand Identity" by Alex — Verified Lv.2
2. "Creative Logo Design" by Jordan — Verified Lv.1
3. "Minimal Logo & Branding" by Sarah

Would you like to see details for any of these?

User: Tell me more about the first one

AI: → Calling get_listing(id: "clx...")

Alex — Premium Brand Identity
• Category: Design → Logo Design
• Verified Level: 2 (Premium)
• Available channels: telegram ✓, discord ✓
• Style: Minimalist, Modern
• Turnaround: 3-5 days

Shall I send a match request?

Authentication

All MCP tools use your API key for authentication. Generate one from your Dashboard → API Keys page.

The same rate limits and usage tracking apply as the REST API. See Rate Limits for details.

Previous ← REST API Next CLI →