POST
/
api
/
v1
/
mcp-servers
curl --request POST \
  --url https://api.kambrium.com/api/v1/mcp-servers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "server_type": "pipedrive",
  "name": "My Pipedrive Connection",
  "description": "Connection to my Pipedrive CRM",
  "auth_method": "api_key",
  "api_key": "pk_abc123",
  "oauth2_client_id": "oauth_client_123",
  "oauth2_client_secret": "oauth_secret_456",
  "oauth2_scopes": [
    "read",
    "write"
  ],
  "config": {
    "domain": "mycompany.pipedrive.com"
  }
}'
{
  "message": "MCP server connection created successfully",
  "connection": {
    "connection_id": "conn_123abc",
    "mcp_server_id": "mcp_456def",
    "server_type": "pipedrive",
    "name": "My Pipedrive Connection",
    "description": "Connection to Pipedrive CRM",
    "status": "active",
    "auth_method": "api_key",
    "oauth2_client_id": "oauth_client_123",
    "oauth2_scopes": [
      "<string>"
    ],
    "config": {},
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

​
Overview

This endpoint creates a new MCP server connection, allowing users to connect to supported integrations like Pipedrive, HubSpot, Salesforce, and others.

​
Prerequisites

  • Valid OAuth Token - Bearer token with mgmt.write scope
  • Integration Support - The integration must be available and supported

​
Request

POST /api/v1/mcp-servers

​
Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token from OAuth authentication
Content-TypestringYesMust be application/json

​
Request Body

{
  "mcp_server": "pipedrive",
  "access_type": "write",
  "api_key": "your-api-key-here"
}

​
Request Fields

FieldTypeRequiredDescription
mcp_serverstringYesIntegration name (e.g., “pipedrive”, “hubspot”)
access_typestringYesAccess level: “read”, “write”, or “individual”
api_keystringYesAPI key for the integration

​
Access Types

  • read - Read-only access to integration data
  • write - Full read/write access to integration data
  • individual - Custom access with specific tool selections

​
Response

​
Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": 123,
    "mcp_server_name": "Pipedrive",
    "api_key_verification_status": "pending",
    "oauth2_client_id": "client_abc123",
    "oauth2_scopes": ["mcp.read", "mcp.write"],
    "agent_enabled": true,
    "disabled_tools": [],
    "created_at": "2025-06-27T10:30:00Z"
  }
}

​
Response Fields

FieldTypeDescription
successbooleanWhether the request was successful
data.idintegerUnique identifier for the connection
data.mcp_server_namestringHuman-readable name of the integration
data.api_key_verification_statusstringAPI key validation status (“pending”, “verified”, “failed”)
data.oauth2_client_idstringOAuth2 client ID for MCP server communication
data.oauth2_scopesarrayOAuth2 scopes granted for this connection
data.agent_enabledbooleanWhether the connection is enabled for agent use
data.disabled_toolsarrayList of disabled tool IDs (empty for non-individual access)
data.created_atstringISO timestamp when connection was created

​
Error Responses

​
Bad Request (400)

{
  "detail": "Invalid MCP server or access type specified"
}

​
Unauthorized (401)

{
  "detail": "Authentication credentials were not provided."
}

​
Forbidden (403)

{
  "detail": "You do not have permission to create connections."
}

​
Internal Server Error (500)

{
  "detail": "Failed to create connection: database error"
}

​
Examples

​
Create Pipedrive Connection

curl -X POST "https://api.kambrium.com/api/v1/mcp-servers" \
  -H "Authorization: Bearer your_oauth_token" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_server": "pipedrive",
    "access_type": "write",
    "api_key": "your-pipedrive-api-key"
  }'

​
Response

{
  "success": true,
  "data": {
    "id": 123,
    "mcp_server_name": "Pipedrive",
    "api_key_verification_status": "pending",
    "oauth2_client_id": "client_abc123",
    "oauth2_scopes": ["mcp.read", "mcp.write"],
    "agent_enabled": true,
    "disabled_tools": [],
    "created_at": "2025-06-27T10:30:00Z"
  }
}

​
Create HubSpot Connection (Read-only)

curl -X POST "https://api.kambrium.com/api/v1/mcp-servers" \
  -H "Authorization: Bearer your_oauth_token" \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_server": "hubspot",
    "access_type": "read",
    "api_key": "your-hubspot-api-key"
  }'

​
Implementation Notes

​
Automatic Configuration

  • agent_enabled is automatically set to true
  • api_key_verification_status starts as “pending” and is verified asynchronously
  • oauth2_client_id and oauth2_scopes are automatically generated
  • disabled_tools array is empty for “read” and “write” access types

​
OAuth Client Registration

  • An OAuth2 client is automatically created for the connection
  • OAuth credentials are generated and associated with the connection
  • This enables secure tool execution with proper scoping

​
Validation

  • Integration name is validated against available integrations
  • Access type is validated against supported values
  • API key format is validated before storage

​
Database Storage

  • Connection is stored in the web database
  • Database IDs are mapped from user-friendly names
  • All fields are properly validated before creation

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Response

201 - application/json

MCP server connection created successfully

The response is of type object.