Traceable MCP Server

The Traceable MCP Server enables you, AI assistants, and agents to securely interact with Traceable using the Model Context Protocol (MCP). It exposes Traceable’s API security data, observations, and analysis capabilities in a structured, machine-consumable format, while enforcing the same authentication and authorization controls as the Traceable platform.

By integrating with MCP, Traceable allows AI systems to query API inventory, analyze security findings, and understand runtime behavior without direct access to raw infrastructure or internal systems.

What will you learn in this topic?

By the end of this topic, you will understand:

What the Traceable MCP server is and how it works.
Why and when you should use the MCP server.
How Traceable handles the authentication for the MCP server.
The tools and capabilities available through MCP.
The data sources through which Traceable extracts data.
The security considerations and limitations when using the MCP.
The prerequisites required to configure and access the MCP server.
The steps to configure the MCP server.

Why you should use the Traceable MCP server

The Traceable MCP Server is built for you to use AI assistants or agents with your API security data.

You should use Traceable MCP when you want to:

Allow AI assistants to query API inventory and security findings using prompts.
Investigate API threats and unusual behavior faster using natural language queries.
Provide AI tools with controlled, read-only access to API security data.
Understand how runtime API behavior maps to security policies without manually navigating the Traceable platform.

The MCP Server ensures that AI access to Traceable data is secure, limited to the appropriate scope, and auditable, making it suitable for production environments.

Available tools and capabilities

The Traceable MCP server exposes the following set of tools that allow AI agents and clients to query and analyze API security data:

Tool Category	Tool	Description
Query and Data Retrieval	`get_attribute_mappings`	Returns valid attribute mappings for entities like `API`, `SERVICE`, `DOMAIN`, `BACKEND`, `ACTOR`, and `BACKEND_API`. You must call this tool before calling `get_graphql_query_template_details`.
	`get_graphql_query_template_details`	Returns GraphQL query templates for supported queries, such as `entities`, `vulnerabilitiesV3`, `explore`, `searchAst`, `threatActivity`, and `submitAnalyticsQueryBatch`. For more information, see Supported query types. You must call this before executing any GraphQL query.
	`execute_graphql_query`	Executes a valid GraphQL query against the Traceable platform. You must call the above tool first.
Time and Filtering	`get_query_time_range`	Returns UTC start and end timestamps for time-based filtering. Accepts duration, start time, or end time (in milliseconds).
	`get_threat_activity_timerange`	Generates optimized time ranges for threat activity queries, expanding windows to capture boundary-spanning events.
	`get_vuln_enum_filter_supported_values`	Returns supported enum values for vulnerability filters, such as `STATUS`, `SEVERITY`, `OWASP`, and `VULNERABILITY_CATEGORY`.
Sensitive Data	`get_datatypes_details_from_datatype_names`	Retrieves metadata for sensitive data types (ID, sensitivity level, suppression status) using data type names such as Personal Identification or Financial Information.
Sensitive Data	`get_datatypes_details_from_datatype_ids`	Retrieves sensitive data type metadata using `dataTypeId` values obtained from prior queries or entity metadata.
API Analysis	`find_apis_by_regex`	Finds API endpoints matching a regex pattern, for example, auth, admin, payment, and upload endpoints.
	`get_api_insights_for_api_id`	Fetches the OpenAPI specification (YAML) for a given API endpoint.
	`get_sample_spans_for_api_id`	Retrieves sample trace spans, such as headers, bodies, cookies, and metadata, for an API from the last 24 hours.
JEXL and Derivation	`validate_jexl_expression`	Validates a JEXL expression against sample spans for a specific API to ensure correct attribute extraction.
JEXL and Derivation	`create_derivation_config`	Creates a derivation configuration using JEXL expressions defined in XML format for entity-based feature extraction.
Fraud Policy	`validate_fraud_policy_sql_query`	Validates SQL queries for fraud policies, checking grammar, safety, and required fields. Must be called before policy creation.
Fraud Policy	`create_fraud_policy`	Creates a fraud policy using a validated SQL query. Requires policy name, description, API ID, and optionally a derivation config ID.
Trends and Display	`calculate_trend_data`	Computes daily or weekly trend data for APIs, issues, or vulnerabilities using backward reconstruction.
Trends and Display	`get_display_urls`	Generates clickable display URLs for entities, threat activities, or explore results. Typically used at the end of workflows.

Supported query types

The get_graphql_query_template_details tool supports the following query types:

Query Name	Description
`entities`	Fetches entities, such as `API`, `SERVICE`, `DOMAIN`, `BACKEND`, `ACTOR`, and `BACKEND_API`.
`vulnerabilitiesV3`	Fetches issues (vulnerabilities) from runtime, gateway, compliance, security testing, and conformance sources.
`explore`	Fetches explore-based datasets, for example, `DOMAIN_EVENT`.
`searchAst`	Fetches API testing scan data across multiple scans.
`threatActivityMetadata`	Fetches metadata for threat activity fields.
`threatActivity`	Fetches threat activity data.
`submitAnalyticsQueryBatch`	Fetches API risk, inventory, updates, deletions, and time-based vulnerability trends.
`getAstHookTests`	Fetches API testing authentication hook test details.

Data sources

The MCP server enables you to query and extract data from the following modules and their corresponding sources:

Module	Sources
Discovery	API Inventory — Provides a detailed catalog of all discovered APIs, including their endpoints, authentication requirements, exposure levels (internal or external), ownership information, and traffic visibility. For more information, see Inventory. Services — Provides a logical grouping of APIs that help you understand which APIs belong to which service and the associated risk. For more information, see Services. Domains — Provides information on internal and external domains connected to the environments, highlighting which domains are public-facing, internal-only, or linked to third parties. For more information, see Domains. Backends — Provides information on connected backend systems and services that receive traffic from APIs, allowing you to identify dependencies, traffic volume, and data sensitivity within backend connections. For more information, see Backends. Sensitive Data — Provides information on API endpoints that process sensitive data, such as Personally Identifiable Information (PII), Social Security Numbers (SSN), or authentication tokens. This helps you identify risks associated with data privacy. For more information, see Sensitive Data. Posture Events — Provides information on discovery-related changes in your API ecosystem. It includes events such as the discovery of issues and the introduction of new services or APIs. This helps you track changes in your security posture over time and highlights areas that may require investigation or remediation. For more information, see Posture Events.
Protection	Threat Actors — Provides information about malicious sources or entities identified by Traceable as potential attackers. This includes details, such as attacker information, origin, activity patterns, and severity levels. This helps you understand who is targeting your APIs. For more information, see Threat Actors. Threat Activities — Provides information about detected attack activities, including APIs and users. This provides visibility into attempted exploits, attack vectors, timestamps, and affected APIs, helping you track threat behavior. For more information, see Threat Activity. Security Events — Provides information on all security-related events captured across your environment. It displays data, such as detections, anomalies, and rules triggered by the threat actor, allowing you to analyze security incidents within your application. APIs under Threat — Provides information on the APIs currently being targeted or showing signs of attack. It provides insights into affected APIs, associated threat types, attack frequency, and risk levels to help prioritize protection measures. For more information, see APIs under Threat.

Module

Sources

Discovery

API Inventory — Provides a detailed catalog of all discovered APIs, including their endpoints, authentication requirements, exposure levels (internal or external), ownership information, and traffic visibility. For more information, see Inventory.
Services — Provides a logical grouping of APIs that help you understand which APIs belong to which service and the associated risk. For more information, see Services.
Domains — Provides information on internal and external domains connected to the environments, highlighting which domains are public-facing, internal-only, or linked to third parties. For more information, see Domains.
Backends — Provides information on connected backend systems and services that receive traffic from APIs, allowing you to identify dependencies, traffic volume, and data sensitivity within backend connections. For more information, see Backends.
Sensitive Data — Provides information on API endpoints that process sensitive data, such as Personally Identifiable Information (PII), Social Security Numbers (SSN), or authentication tokens. This helps you identify risks associated with data privacy. For more information, see Sensitive Data.
Posture Events — Provides information on discovery-related changes in your API ecosystem. It includes events such as the discovery of issues and the introduction of new services or APIs. This helps you track changes in your security posture over time and highlights areas that may require investigation or remediation. For more information, see Posture Events.

Protection

Threat Actors — Provides information about malicious sources or entities identified by Traceable as potential attackers. This includes details, such as attacker information, origin, activity patterns, and severity levels. This helps you understand who is targeting your APIs. For more information, see Threat Actors.
Threat Activities — Provides information about detected attack activities, including APIs and users. This provides visibility into attempted exploits, attack vectors, timestamps, and affected APIs, helping you track threat behavior. For more information, see Threat Activity.
Security Events — Provides information on all security-related events captured across your environment. It displays data, such as detections, anomalies, and rules triggered by the threat actor, allowing you to analyze security incidents within your application.
APIs under Threat — Provides information on the APIs currently being targeted or showing signs of attack. It provides insights into affected APIs, associated threat types, attack frequency, and risk levels to help prioritize protection measures. For more information, see APIs under Threat.

Security considerations

The Traceable MCP server is created with security as the core requirement. When you use the MCP server:

All requests are authenticated using your Traceable Platform API token.
Access to data is enforced using the same role-based access control that applies across the Traceable platform.
You or the AI agent can access only the data permitted for your assigned roles.
The prompts you use determine whether or not Traceable returns IP addresses or sensitive information as part of the results.

By default, the MCP Server is created with read-only access, helping reduce the risk of unintended changes to your security posture.

Limitations

Make note of the following limitations when using the Traceable MCP server:

Policy creation, modification, or enforcement is not available through the MCP server.
Access to raw request or response payloads may be restricted based on your application configuration in the Traceable platform.
MCP capabilities are limited to what the authenticated user is permitted to access in the Traceable platform.

Configuring the MCP server

Traceable provides its MCP server, which you can configure to securely connect AI assistants or agents to your Traceable environment.

Before you begin

Make a note of the following before configuring your MCP server:

Make sure that you have access to the Traceable Public URL for your cluster, for example, api.traceable.ai.
Make sure that you have a valid Platform API token. For the steps to retrieve this, see Public APIs. This token is required to authenticate the user and access the MCP server.

Public MCP endpoint

Traceable exposes the MCP server through the public URL associated with your Traceable cluster. You can specify this URL while configuring the MCP server:

"url": "https://<api.traceable.ai>/mcp"
// Replace the sample cluster URL with the actual URL above

Authentication

The Traceable MCP server uses token-based authentication. This token defines the tenant you can access. For the steps to configure this token, see Public APIs.

Once you generate the token, you must specify this token in the header while configuring the MCP server:

"Authorization": "<AjBxCjdmDEFtGjHxIJ06K2E2LLMjYTEtZTVjY2NiYjRjN2Y1>"
// Replace the sample API token above with the actual token above

Configuration

Traceable provides multiple ways of configuring the MCP server depending on the coding assistant you use:

Claude CLI

Claude Desktop

Cursor

Windsurf

VS Code

To configure the Traceable MCP server, navigate to your Claude CLI and execute the following command:

claude mcp add \
  --transport http \
  traceable-ai \
  https://<Cluster_Public_URL>/mcp \
  --header "Authorization: <Platform_token>"

// Replace the <Cluster_Public_URL> and <Platform_token> placeholders with the actual values

To configure the Traceable MCP server, navigate to your Claude Desktop app and complete the following steps:

Navigate to the app's Settings page.
Under Desktop app, click Developer.
In the MCP servers page, click Edit Config. Claude redirects you to the claude_desktop_config.json file.

Open the file using an editor of your choice and specify the following code:

{
  "mcpServers": {
    "traceable-ai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<Cluster_Public_URL>/mcp",
        "--header",
        "Authorization: <Platform_token>"
      ]
    }
  }
}
// Replace the <Cluster_Public_URL> and <Platform_token> placeholders with the actual values.

Save the file.
Quit the Claude Desktop app, then restart it.

You can now use the Claude Desktop app to interact with the Traceable MCP server.

To configure the Traceable MCP server, navigate to your Cursor app and execute the following command in the mcp.json file. For more information, see Installing MCP servers.

{
  "mcpServers": {
    "traceable-ai": {
      "url": "https://<Cluster_Public_URL>/mcp",   // Replace the <Cluster_Public_URL> placeholder with the actual value
      "headers": {
        "Authorization: <Platform_token>",   // Replace the <Platform_token> placeholder with the actual value
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

To configure the Traceable MCP server, navigate to your Windsurf app and execute the following command in the mcp.json file. For more information, see Connecting to MCP servers.

{
  "mcpServers": {
    "traceable-ai": {
      "serverUrl": "https://<Cluster_Public_URL>/mcp",   // Replace the <Cluster_Public_URL> placeholder with the actual value
      "headers": {
        "Authorization: <Platform_token>",   // Replace the <Platform_token> placeholder with the actual value
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

To configure the Traceable MCP server, navigate to your VS Code app and execute the following command in the mcp.json file. For more information, see Add an MCP server.

{
	"servers": {
		"Traceable": {
			"url": "https://<Cluster_Public_URL>/mcp",   // Replace the <Cluster_Public_URL> placeholder with the actual value
			"headers": {
				"Authorization: <Platform_token>",   // Replace the <Platform_token> placeholder with the actual value
				"Accept": "application/json, text/event-stream"
			}
		}
	}
}