How to Use the Sparkforge MCP Server with AI Agents

The Sparkforge MCP (Model Context Protocol) server lets AI agents read and write Sparkforge data over a standard HTTP protocol. No SDKs, no custom glue. Any client that speaks HTTP — Cursor, Windsurf, OpenAI Playground, custom agents — can call the same set of tools with a Private Integration Token (PIT).

What You Get Out of the Box

The current release ships 36 tools across these areas:

• Calendars: get calendar events, get appointment notes
• Contacts: get, create, update, upsert, search; add and remove tags; list tasks
• Conversations: search, get messages, send a new message
• Locations: get location details, get custom field definitions
• Opportunities: search, get pipelines, get and update by ID
• Payments: get order by ID, list transactions
• Blogs: check slug, create and update posts, get authors, categories, posts, blogs
• Email Templates: create and fetch templates
• Social Media Posts: get accounts, get statistics, create, get, list, and edit posts

Configure Your Client

Add the MCP endpoint and headers to your agent's MCP configuration. Example JSON:

{
  "mcpServers": {
    "sparkforge": {
      "url": "https://services.sparkforgehq.com/mcp/",
      "headers": {
        "Authorization": "Bearer <your-token>",
        "locationId": "<sub-account-id>"
      }
    }
  }
}

Create a Private Integration Token

1. Open the target Sparkforge sub-account.
2. Go to Settings > Private Integrations.
3. Click Create New Integration.
4. Select the scopes you need (see list below).
5. Copy the token and store it securely. It will not be shown again.

Scopes to Enable

• View / Edit Contacts
• View / Edit Conversations
• View / Edit Conversation Messages
• View / Edit Opportunities
• View Calendars and Calendar Events
• View Locations
• View Payment Orders and Transactions
• View Custom Fields
• View Forms
• Check Blog Post Slug
• Create / Update Blog Posts
• View Blog Authors and Categories
• Read Blog Posts and Blog Lists
• Create / Update / Delete Email Templates
• View Email Templates
• View Social Media Accounts and Statistics
• Edit and View Social Media Posts

Make a Tool Call

Python example:

import requests

headers = {
    "Authorization": "Bearer YOUR_PIT_TOKEN",
    "locationId": "YOUR_LOCATION_ID",
}
data = {
    "tool": "contacts_get-contact",
    "input": {"contactId": "abc123"},
}
response = requests.post(
    "https://services.sparkforgehq.com/mcp/",
    headers=headers,
    json=data,
)
print(response.json())

Roadmap

• Per-service MCP servers for tighter, scoped workflows
• An npx package for clients without native HTTP MCP support (such as Claude Desktop)
• OAuth flows for delegated authorization
• Expansion toward 250+ tools so a single agent can orchestrate every Sparkforge module