API Reference

This document describes the REST API endpoints that Agnost SDKs use to communicate with the Agnost Analytics backend.

Base URL

Production: https://api.agnost.ai Custom deployments may use different base URLs.

Authentication

All API requests require an organization ID provided via the X-Org-Id header.

Never expose your organization ID in client-side code. The SDKs are designed for server-side use only.

Common Headers

All endpoints require these headers:

Header	Value	Description
`Content-Type`	`application/json`	Request body format
`X-Org-Id`	`{organization_id}`	Your organization identifier

Create Session

Creates a new analytics session for tracking MCP server interactions.

POST /api/v1/capture-session

Description

A session represents a single connection to an MCP server. Sessions are created when:

An MCP client connects to the server
The SDK first initializes tracking
A new server instance starts

Sessions include metadata about the server configuration, available tools, and optionally user identification.

Request Body

session_id

string

required

Unique identifier for this session (UUID format), generated by SDK

client_config

string

required

Name or identifier of the MCP client (e.g., “claude-desktop”, “vscode”, “custom-client”)

connection_type

string

Type of connection (reserved for future use, can be empty)

string

IP address of the client (reserved for future use, can be empty)

tools

array

List of tool names available on this MCP server

user_data

object

User identification data (shape defined by identify function). Common fields:

userId (string): Unique user identifier (recommended)
email (string): User’s email address
role (string): User’s role or permission level
Additional custom fields as needed

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_config": "claude-desktop",
  "connection_type": "",
  "ip": "",
  "tools": ["get_weather", "search_web", "calculate"],
  "user_data": {
    "userId": "user123",
    "email": "[email protected]",
    "role": "admin"
  }
}

Response

session_id

string

Echo of the session ID from the request

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Codes

200 OK

Session created successfully

201 Created

Session created successfully (alternative)

400 Bad Request

Invalid request body

401 Unauthorized

Missing or invalid organization ID

500 Internal Server Error

Server error

SDK Usage

Sessions are created automatically by the SDKs when tracking is enabled:

TypeScript
Python
Go

import { trackMCP } from 'agnost';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server({ name: 'my-server', version: '1.0.0' }, {});

// Session is created automatically when tracking starts
trackMCP(server, 'your-org-id', {
  identify: (req, env) => ({
    userId: env?.USER_ID || 'anonymous',
    email: env?.USER_EMAIL
  })
});

Record Event

Records an analytics event for a tool, resource, or prompt execution.

POST /api/v1/capture-event

Description

Events track individual interactions with MCP primitives (tools, resources, prompts). Each event includes:

What was called (primitive type and name)
Performance metrics (latency)
Success/failure status
Optionally, input arguments and output results

Request Body

session_id

string

required

Session ID from the session creation response

primitive_type

string

required

Type of primitive: "tool", "resource", or "prompt"

primitive_name

string

required

Name of the tool/resource/prompt that was called

latency

number

required

Execution time in milliseconds

success

boolean

required

Whether the execution succeeded (true) or failed (false)

args

string

JSON-encoded string of input arguments. Omitted if disableInput: true

result

string

JSON-encoded string of output/result. Omitted if disableOutput: true

Primitive Types

Type	Description	Example
`tool`	MCP tool execution	`get_weather`, `search_database`, `send_email`
`resource`	MCP resource access	`file://readme.txt`, `db://users`
`prompt`	MCP prompt usage	`code_review_template`, `summarize_text`

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "primitive_type": "tool",
  "primitive_name": "get_weather",
  "latency": 342,
  "success": true,
  "args": "{\"location\":\"San Francisco\",\"units\":\"celsius\"}",
  "result": "{\"temperature\":18,\"conditions\":\"partly cloudy\"}"
}

Response

success

boolean

Whether the event was recorded successfully

event_id

string

Unique identifier for this event

{
  "success": true,
  "event_id": "evt_abc123def456"
}

Response Codes

200 OK

Event recorded successfully

201 Created

Event recorded successfully (alternative)

400 Bad Request

Invalid request body

401 Unauthorized

Missing or invalid organization ID

404 Not Found

Session ID not found

500 Internal Server Error

Server error

SDK Usage

Events are recorded automatically by the SDKs when tools are called:

TypeScript
Python
Go

// Events are automatically recorded when tools are called
// through the tracked server

SDK Behavior

Batching and Queuing

SDKs implement intelligent batching and queuing to optimize API usage:

TypeScript
Python
Go

Events are queued and sent in batches (default: 5 events per batch)
Configurable via batchSize option
Can be disabled with enableRequestQueuing: false

trackMCP(server, 'org-id', {
  batchSize: 10,
  enableRequestQueuing: true
});

Retry Logic

TypeScript
Python
Go

Configurable retry attempts (default: 3)
Configurable retry delay (default: 1000ms)

trackMCP(server, 'org-id', {
  maxRetries: 5,
  retryDelay: 2000
});

Error Handling

All SDKs follow a fail-safe approach:

Analytics failures do not disrupt MCP server operation

Failed API calls are logged but not propagated

Tool execution continues even if event recording fails

Session Caching

Sessions are cached by the SDK to avoid redundant API calls:

Session IDs are stored in memory by session key
Same session ID is reused for the lifetime of the server instance
Cache is cleared on SDK shutdown

Privacy Controls

SDKs respect privacy configuration to exclude sensitive data:

TypeScript
Python
Go

// Disable input tracking
trackMCP(server, 'org-id', { disableInput: true });

// Disable output tracking
trackMCP(server, 'org-id', { disableOutput: true });

Rate Limiting

Current implementation does not enforce rate limits, but this may change in future versions.

Recommended practices:

Use SDK’s built-in batching to reduce request volume
Implement exponential backoff for retries
Monitor your organization’s API usage

Troubleshooting

Common Errors

400 Bad Request

Possible causes:

Missing required fields
Invalid JSON format
Invalid UUID format for session_id

Solution: Validate your request body against the schemas above

401 Unauthorized

Possible causes:

Missing X-Org-Id header
Invalid organization ID
Organization not active

Solution: Check your organization ID at app.agnost.ai

404 Not Found

Possible causes:

Session ID does not exist (for events)

Solution: Ensure session is created before sending events

500 Internal Server Error

Possible causes:

Backend service issue

Solution: Contact support with request details

Debug Logging

Enable debug logging in SDKs to troubleshoot API issues:

Python
Go

import logging
logging.getLogger("agnost").setLevel(logging.DEBUG)

API Versioning

Current API version: v1

Version is specified in the URL path: /api/v1/... Future versions will use /api/v2/, /api/v3/, etc.

Support

For API issues or questions:

Documentation: docs.agnost.ai
GitHub Issues: agnost-sdks/issues
Email: [email protected]

Getting Started

MCP Toolbox

Step-by-Step Guides

Reference

Internal

Base URL

Authentication

Common Headers

Create Session

Description

Request Body

Response

Response Codes

SDK Usage

Record Event

Description

Request Body

Primitive Types

Response

Response Codes

SDK Usage

SDK Behavior

Batching and Queuing

Retry Logic

Error Handling

Session Caching

Privacy Controls

Rate Limiting

Troubleshooting

Common Errors

Debug Logging

API Versioning

Support

Getting Started

MCP Toolbox

Step-by-Step Guides

Reference

Internal

​Base URL

​Authentication

​Common Headers

​Create Session

​Description

​Request Body

​Response

​Response Codes

​SDK Usage

​Record Event

​Description

​Request Body

​Primitive Types

​Response

​Response Codes

​SDK Usage

​SDK Behavior

​Batching and Queuing

​Retry Logic

​Error Handling

​Session Caching

​Privacy Controls

​Rate Limiting

​Troubleshooting

​Common Errors

​Debug Logging

​API Versioning

​Support

Base URL

Authentication

Common Headers

Create Session

Description

Request Body

Response

Response Codes

SDK Usage

Record Event

Description

Request Body

Primitive Types

Response

Response Codes

SDK Usage

SDK Behavior

Batching and Queuing

Retry Logic

Error Handling

Session Caching

Privacy Controls

Rate Limiting

Troubleshooting

Common Errors

Debug Logging

API Versioning

Support