Integration Guide

Learn how to connect your applications to Testra MCP servers, covering authentication, using endpoints, and example code snippets.

---

1. Authentication

All API requests to Testra require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Make sure to keep your API key secure and do not expose it in client-side code.

---

2. Base URL

All API calls use the following base URL:

https://api.testra.ai/v1

---

3. Discovering Servers

You can search for MCP servers via the /servers/search endpoint with filters for categories, tags, uptime, and more. Refer to the Server Discovery API for full details.

Example (curl):

curl "https://api.testra.ai/v1/servers/search?category=defi&tags=price-oracle" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

---

4. Fetching Server Details

Get detailed metadata about a server using its serverId:

curl "https://api.testra.ai/v1/servers/{serverId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

---

5. Calling Functions on MCP Servers

To execute a function exposed by an MCP server, send a POST request to the /execute endpoint of that server:

Request

POST https://example.mcp.server/execute
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Body Example

{
  "function": "get_exchange_rate",
  "input": {
    "from": "USD",
    "to": "EUR"
  }
}

---

6. Handling Responses

Typical response structure:

{
  "output": {
    "rate": 0.9254
  }
}

Check for HTTP status codes and handle errors such as 401 Unauthorized or 500 Internal Server Errorappropriately.

---

7. SDKs and Code Samples

Testra provides SDKs to simplify integration:

JavaScript Example

import { TestraClient } from 'testra-sdk';

const client = new TestraClient({ apiKey: 'YOUR_API_KEY' });

async function getRate() {
  const response = await client.execute('srv_price_oracle_v1', 'get_exchange_rate', {
    from: 'USD',
    to: 'EUR'
  });
  console.log(response.output.rate);
}

getRate();

Python Example

from testra_sdk import TestraClient

client = TestraClient(api_key='YOUR_API_KEY')

response = client.execute('srv_price_oracle_v1', 'get_exchange_rate', {
    'from': 'USD',
    'to': 'EUR'
})
print(response['output']['rate'])

---

8. Best Practices

• Cache server discovery results to reduce API calls.

• Validate server capabilities before calling functions.

• Use the Testra Inspector during development for live debugging.

• Monitor API rate limits to avoid throttling.