Skip to main content

MCP API

The MCP API is how an AI assistant, or your own code, asks questions of your SparkLogs data. It uses the Model Context Protocol (MCP), the open standard AI apps use to reach tools and data. The server runs in the SparkLogs cloud. You install and host nothing.

Your AI

Any MCP client, or your own code
MCP over HTTPS

SparkLogs MCP API

MCP server
  • Signs you in: OAuth, or an API token
  • Checks each call against your access and scopes
  • Records each call in the audit log
read-only by default

Your workspace

Logs and patterns
Device health and state
Agent and collection status
Workspace managementonly with your explicit authorization

The same connection can manage a workspace's setup, such as organizations, agents and access, when you authorize it. For your own automation of that setup, use the REST API.

Connect​

Global MCP API endpointhttps://mcp.sparklogs.app/mcp

Every connection goes to this one address, whatever region your workspace is in.

You haveDo this
Claude, Codex, Cursor or IronRunbookUse the SparkLogs plugin, which sets up the connection. See Connect Your AI.
Microsoft Copilot StudioFollow its setup page.
Any other MCP clientAdd the address above as an MCP server and sign in with OAuth when the client prompts.
A client that cannot sign in with OAuth, or your own codeSend an API token as a bearer token in the Authorization header.

An AI app without the SparkLogs plugin has no guidance on how to use the tools. Copy the Agent Instruction Template into the app's system or instruction field.

SparkLogs works beside the other MCP servers your AI uses, such as your RMM, PSA and ticketing.

What a connection can reach​

  • Your access. An AI app acts as the person who approved it, and an API token has access of its own. Either can reach only the organizations that access covers.
  • Scopes. The scopes you approve narrow that further. Without events:read, for example, an AI works from counts, patterns and device health and cannot read raw log lines.
  • Read-only by default. The tools query logs, device health and other data. Tools that manage your workspace work only with your explicit authorization: a write scope you approved, or an API token that permits changes.
  • No credentials in answers. A tool call does not return the secret of an API token, ingest key or registration token.
  • Audit. Every tool call is recorded in the audit log.

See AI Trust Principles for how we engineer for secure collaboration with AI.

Tools​

ToolWhat it is forScope it needs
Start
server_infoCheck the connection: the server's version and the workspace you are signed in to.None: any connection
resolve_scopeTurn the name of a client, site or device into the organizations and devices to ask about.workspace:read
Learn what data is there
list_sourcesWhich devices and other sources sent data in a time window, and whether collection is healthy.any of workspace:read, events:query
query_scope_activityWhere the activity is: event counts by source, application or reason code.events:query
list_fieldsWhich fields the log data in a time window has.events:query
describe_tablesWhich tables can be queried, and their columns.None: any connection
Ask questions
query_device_healthDevice health over time, for one device or the fleet: conditions, inventory, performance and changes.events:query or devices:read, depending on what you ask for
query_event_counts_by_severityCount events over time, by severity.events:query, plus events:read for some questions
query_logsSearch and read log events.events:read
describe_patternWhat a recurring message pattern is, how often it occurs, and on how many devices.events:query
query_tableQuery, group and aggregate any of the tables.events:read or events:query or analytics:read, depending on what you ask for
Work with a result
refine_query_resultFilter, group, sort or page a result you already have.The scope the earlier call needed
get_query_metadataWhat a result you already have holds.The scope the earlier call needed
Manage the workspace
describe_api_operationsList the REST API calls this connection can make.None: any connection
call_api_readMake a REST API call that reads.The scope of the REST call it makes
call_api_writeMake a REST API call that changes something.The scope of the REST call it makes
call_api_destructiveMake a REST API call that deletes or revokes something.The scope of the REST call it makes
Feedback
send_sparklogs_feedbackSend feedback to the SparkLogs team, when the person asks to.None: any connection

A tool with more than one scope listed works with any one of those scopes. Every connection also carries workspace:read.

You can use MCP with your AI assistant to manage your SparkLogs workspace. The three call_api_ tools allow you to invoke REST API calls using MCP.

Permissions are enforced based on the specific REST API call you invoke. When you connect your AI app, by default it will not grant scopes to modify your workspace or perform destructive actions. Grant these permissions only when they are needed, and appropriately safeguard any tokens or OAuth sessions where these permissions were granted.

REST API calls that reveal or rotate a credential are intentionally not offered through MCP so that secrets do not enter the context of an LLM.

When you delete an agent through MCP, the agent stays installed on the device for at least 7 days. Restoring the agent within that time cancels the uninstall. To uninstall sooner, delete the agent in the app or with the REST API directly.

From your own code​

Any MCP client library can call our MCP server with an API token. See MCP API code examples for Python and TypeScript examples.