# 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](https://modelcontextprotocol.io/) (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: [Claude](https://sparklogs.com/docs/it-fleet-intelligence/connect/claude.md), [Codex](https://sparklogs.com/docs/it-fleet-intelligence/connect/codex.md), [Copilot Studio](https://sparklogs.com/docs/it-fleet-intelligence/connect/copilot.md), [Cursor](https://sparklogs.com/docs/it-fleet-intelligence/connect/cursor.md), [IronRunbook](https://sparklogs.com/docs/it-fleet-intelligence/connect/ironrunbook.md), any other MCP client, or your own code.
- SparkLogs MCP API: one MCP server at `https://mcp.sparklogs.app/mcp`, reached over HTTPS. It signs you in with OAuth or an API token, checks each call against your access and scopes, and records each call in the audit log.
- Your workspace: the tools read logs and patterns, device health and state, and agent and collection status. They are read-only by default; tools that manage the workspace work only 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](https://sparklogs.com/docs/api.md).

## Connect

Global MCP API endpoint: `https://mcp.sparklogs.app/mcp`

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

| You have | Do this |
| - | - |
| Claude, Codex, Cursor or IronRunbook | Use the SparkLogs plugin, which sets up the connection. See [Connect Your AI](https://sparklogs.com/docs/it-fleet-intelligence/connect.md). |
| Microsoft Copilot Studio | Follow [its setup page](https://sparklogs.com/docs/it-fleet-intelligence/connect/copilot.md). |
| Any other MCP client | Add 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 code | Send an [API token](https://sparklogs.com/docs/workspace/access.md#api-tokens) 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](https://sparklogs.com/docs/it-fleet-intelligence/connect/agent-instructions.md) 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](https://sparklogs.com/docs/workspace/access.md#oauth-consent) 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](https://sparklogs.com/docs/workspace/audit-logs.md).

See [AI Trust Principles](https://sparklogs.com/docs/it-fleet-intelligence/trust-principles.md) for how we engineer for secure collaboration with AI.

## Tools

| Tool | What it is for | Scope it needs |
| - | - | - |
| **Start** | | |
| `server_info` | Check the connection: the server's version and the workspace you are signed in to. | None: any connection |
| `resolve_scope` | Turn the name of a client, site or device into the organizations and devices to ask about. | `workspace:read` |
| **Learn what data is there** | | |
| `list_sources` | Which devices and other sources sent data in a time window, and whether collection is healthy. | any of `workspace:read`, `events:query` |
| `query_scope_activity` | Where the activity is: event counts by source, application or reason code. | `events:query` |
| `list_fields` | Which fields the log data in a time window has. | `events:query` |
| `describe_tables` | Which tables can be queried, and their columns. | None: any connection |
| **Ask questions** | | |
| `query_device_health` | Device 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_severity` | Count events over time, by severity. | `events:query`, plus `events:read` for some questions |
| `query_logs` | Search and read log events. | `events:read` |
| `describe_pattern` | What a recurring message pattern is, how often it occurs, and on how many devices. | `events:query` |
| `query_table` | Query, 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_result` | Filter, group, sort or page a result you already have. | The scope the earlier call needed |
| `get_query_metadata` | What a result you already have holds. | The scope the earlier call needed |
| **Manage the workspace** | | |
| `describe_api_operations` | List the REST API calls this connection can make. | None: any connection |
| `call_api_read` | Make a REST API call that reads. | The scope of the REST call it makes |
| `call_api_write` | Make a REST API call that changes something. | The scope of the REST call it makes |
| `call_api_destructive` | Make a REST API call that deletes or revokes something. | The scope of the REST call it makes |
| **Feedback** | | |
| `send_sparklogs_feedback` | Send 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](https://sparklogs.com/docs/api/reference.md) 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](https://sparklogs.com/docs/mcp/code-examples.md) for Python and TypeScript examples.

---

Source: <https://sparklogs.com/docs/mcp>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
