Skip to main content

​
Overview

While Tadata offers many pre-built connectors, you can also bring your own APIs:
  • Internal/private APIs not available in our catalog
  • Custom business logic specific to your organization
  • Existing MCP servers you’ve already built
This guide covers three approaches to bringing your own integrations.

​
Approach 1: Upload OpenAPI Specification

Best for: REST APIs with OpenAPI/Swagger documentation

​
Prerequisites

  • OpenAPI 3.0+ specification file (JSON or YAML)
  • Or a public URL hosting your OpenAPI spec
  • API credentials (API key, OAuth client ID/secret, etc.)

​
Step 1: Access Upload Interface

  1. Navigate to Toolsets → Create New
  2. Select From OpenAPI Specification
  3. Choose upload method:
    • Upload File: Drag and drop your .json or .yaml file
    • URL: Enter the URL to your OpenAPI spec (e.g., https://api.yourservice.com/openapi.json)
Many services host their OpenAPI specs at /openapi.json, /swagger.json, or /api-docs. Check your API documentation.

​
Step 2: Review Detected Tools

Tadata automatically parses your OpenAPI spec and generates tools from your API endpoints. You’ll see:
  • Tool count: Number of operations found
  • Authentication methods: Detected from securitySchemes
  • Base URL: API endpoint base URL
  • Tool list: All generated tools with descriptions
Review the detected tools and their descriptions to ensure they match your API.

​
Step 3: Configure Authentication

Choose your authentication method based on what your API supports:
  • API Key (Header)
  • API Key (Query Param)
  • OAuth 2.0
  • Basic Auth
Most common for internal APIs
Configuration
{
  "authType": "header",
  "headerName": "Authorization",
  "headerPrefix": "Bearer ",
  "apiKey": "your-api-key-here"
}
Examples:
  • Authorization: Bearer sk_live_abc123
  • X-API-Key: abc123
  • X-Auth-Token: token123
Custom Header Prefixes: Some APIs require specific prefixes like Token , Api-Key , or no prefix at all. Check your API documentation.

​
Step 4: Customize and Optimize (Optional)

You can customize tool definitions and apply Tadata’s optimizations:
  • Edit tool names and descriptions: Make them more intuitive for AI agents
  • Apply optimizations: Enable response filtering, compression, and token reduction
  • Configure tool selection: Use AI-powered tool selection for your use case
Learn more about optimization features in our Optimization Guide - including response compression, filtering, and knowledge indexing.

​
Step 5: Test in Playground

Test your tools in the Playground to verify they work correctly:
  1. Click Open Playground
  2. Test with sample requests
  3. Verify responses and error handling
Once testing passes, your toolset is automatically deployed and ready to use!

​
Approach 2: Integrate Existing MCP Server

Best for: You’ve already built an MCP server and want to proxy it through Tadata for analytics and optimization

​
Prerequisites

  • Running MCP server with accessible endpoint (must be internet-accessible, not localhost)
  • MCP server URL (HTTP or SSE transport)

​
Setup

  1. Navigate to Toolsets → Create New
  2. Select Integrate Existing MCP Server
  3. Enter your MCP server URL
Authentication Handling: Tadata automatically detects and handles authentication:
  • OAuth with DCR: Automatically configured if your server supports Dynamic Client Registration
  • OAuth without DCR: You can provide OAuth client credentials (client ID, client secret, auth URLs)
  • Manual credentials: If OAuth fails, provide authentication details (API key, headers, etc.)
  1. Click Test Connection - Tadata verifies connectivity
  2. Tadata fetches available tools from your server
  3. Select which tools to expose
  4. Your toolset is automatically deployed

​
Benefits of Proxying

Even if you have a working MCP server, proxying through Tadata gives you:
  • Analytics: Track tool usage, performance, errors
  • Optimization: Enable compression, filtering, projection
  • Monitoring: Get alerts on failures
  • Custom Domains: Host on your own domain
  • Unified Management: Manage all toolsets in one place

​
Approach 3: Request Connector Addition

Best for: Popular APIs that aren’t in our catalog yet If you need a connector for a well-known service:
  1. Visit tadata.com/request-connector
  2. Submit the service details:
    • Service name and website
    • API documentation link
    • Use case description
    • Expected usage volume
  3. Our team will review and prioritize
  4. We’ll notify you when the connector is available
We prioritize connectors based on community demand. Upvote existing requests to increase priority!

​
Best Practices

​
OpenAPI Specs

Older Swagger 2.0 specs work but may have limitations. Upgrade to OpenAPI 3.0+ for:
  • Better schema definitions
  • Improved authentication options
  • More detailed parameter validation
Write clear descriptions for operations:✅ Good: “Create a new issue with title, description, and priority. Returns the created issue with ID and timestamp.”❌ Bad: “POST /issues”AI agents use descriptions to select the right tool.
Include all parameters with:
  • Type (string, integer, boolean, etc.)
  • Required vs. optional
  • Default values
  • Enums for fixed choices
  • Examples
This helps AI agents construct valid requests.
Use versioned URLs (e.g., /api/v1/, /api/v2/) to avoid breaking changes. Update your OpenAPI spec URL when you deploy new versions.

​
Authentication

Create API keys with minimal necessary permissions:
  • Read-only keys for read operations
  • Separate keys for development vs. production
  • Revokable keys for testing
Set reminders to rotate API keys every 90 days. Tadata will notify you if authentication fails.
Before testing tools, verify authentication:
  1. Use a simple read operation
  2. Confirm you get expected data (not 401/403 errors)
  3. Then test write operations

​
Troubleshooting

Symptoms: “Invalid OpenAPI spec” errorSolutions:
  • Validate your spec at editor.swagger.io
  • Check for syntax errors (JSON/YAML formatting)
  • Ensure it’s OpenAPI 3.0+ format
  • Remove unsupported extensions
Symptoms: “401 Unauthorized” or “403 Forbidden” in PlaygroundSolutions:
  • Double-check API key is correct
  • Verify header name and prefix (e.g., “Bearer ” with space)
  • Confirm the API key has necessary permissions
  • Test the API directly with curl/Postman first
Symptoms: Tools execute in Playground but fail when used by Claude/CursorSolutions:
  • Check MCP config syntax in Claude Desktop / Cursor
  • Verify the toolset URL is correct
  • Restart the AI application completely
  • Review error logs in Analytics
Symptoms: “Cannot connect to MCP server” errorSolutions:
  • Verify the server URL is accessible from internet (not localhost)
  • Check firewall rules allow Tadata IP ranges
  • Confirm transport type (HTTP vs. SSE) is correct
  • Test the MCP server directly with curl

​
Next Steps

Test in Playground

Validate your custom toolset works correctly

Configure Authentication

Advanced authentication configuration

Enable Optimization

Optimize responses for token efficiency

View Analytics

Monitor usage and performance