# MCP API Code Examples

Your own automation can call the same tools an AI assistant uses.
You need an MCP client library and an API token.

## What you need

- **An API token.** Create a personal or workspace token in the app under **Workspace Settings**, then **Access**. See [API tokens](https://sparklogs.com/docs/workspace/access.md#api-tokens). A browser session cannot call the MCP server.
- **The server address:** `https://mcp.sparklogs.app/mcp`, for every region.
- **An MCP client library** that speaks streamable HTTP. The server keeps no session between calls.

Set two environment variables for the examples below:

```bash
export SPARKLOGS_MCP_URL='https://mcp.sparklogs.app/mcp'
export SPARKLOGS_API_TOKEN='sl_...'
```

Tested with `mcp` 2.3.0 (Python) and `@modelcontextprotocol/sdk` 1.32.2 (Node 24).

## Python

```bash
pip install mcp==2.3.0
```

```python
"""Connects to the SparkLogs MCP server with an API token, lists the tools and calls two of them.

SPARKLOGS_MCP_URL is the server's MCP endpoint; SPARKLOGS_API_TOKEN is an API token.
"""

import asyncio
import os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client


async def main() -> None:
    url = os.environ["SPARKLOGS_MCP_URL"]
    headers = {"Authorization": f"Bearer {os.environ['SPARKLOGS_API_TOKEN']}"}
    async with httpx2.AsyncClient(headers=headers) as http:
        async with Client(streamable_http_client(url, http_client=http)) as client:
            listed = await client.list_tools()
            print(f"{len(listed.tools)} tools: {', '.join(t.name for t in listed.tools)}")
            for name, args in [
                ("server_info", {}),
                ("resolve_scope", {"external_investigation_id": "sample-client-check"}),
            ]:
                result = await client.call_tool(name, args)
                text = "\n".join(c.text for c in result.content if c.type == "text")
                print(f"--- {name} (isError={result.is_error})\n{text}")


asyncio.run(main())
```

## TypeScript

```bash
npm install @modelcontextprotocol/sdk@1.32.2
```

```typescript
// Connects to the SparkLogs MCP server with an API token, lists the tools and calls two of them.
// SPARKLOGS_MCP_URL is the server's MCP endpoint; SPARKLOGS_API_TOKEN is an API token.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const url = process.env.SPARKLOGS_MCP_URL;
const token = process.env.SPARKLOGS_API_TOKEN;
if (!url || !token) {
  throw new Error("set SPARKLOGS_MCP_URL and SPARKLOGS_API_TOKEN");
}

const transport = new StreamableHTTPClientTransport(new URL(url), {
  requestInit: { headers: { Authorization: `Bearer ${token}` } },
});
const client = new Client({ name: "sparklogs-sample-node", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(`${tools.length} tools: ${tools.map((t) => t.name).join(", ")}`);

for (const [name, args] of [
  ["server_info", {}],
  ["resolve_scope", { external_investigation_id: "sample-client-check" }],
] as const) {
  const result = await client.callTool({ name, arguments: args });
  const text = (result.content as Array<{ type: string; text?: string }>)
    .filter((c) => c.type === "text")
    .map((c) => c.text)
    .join("\n");
  console.log(`--- ${name} (isError=${result.isError ?? false})\n${text}`);
}

await client.close();
```

## What the examples do

Each example shows how to connect, list the tools, and call two tools: `server_info`, then `resolve_scope`.
The output is the tool names, then each tool's answer as text.

`resolve_scope` and the query tools take `external_investigation_id`: a label of your choosing that ties the calls of one piece of work together in the audit log.

Read the tool list from the server each time you connect.
Each entry in that list gives the tool's parameters and how to use it.

## When a call is refused

- **A token that is missing, revoked or expired** is refused when you connect, as it is by the [REST API](https://sparklogs.com/docs/api/authentication.md#when-a-token-is-refused).
- **A token without the scope a tool needs** still connects. The tool call returns a result marked as an error, and its text names the scope to add. The HTTP status is 200.

## Limits

- The three `call_api_` tools share the REST API's limit of 1,200 calls a minute for each token. See [Rate limits](https://sparklogs.com/docs/api/rate-limits.md).
- A request body can be at most 1 MiB.

Every tool call is recorded in the [audit log](https://sparklogs.com/docs/workspace/audit-logs.md).

---

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