> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.phonic.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.phonic.co/_mcp/server.

# Create

POST https://api.phonic.ai/v1/mcp_servers
Content-Type: application/json

Creates an MCP server in the authenticated workspace and project. Phonic connects to the server, lists its tools and saves them alongside the server, so the server must be reachable from Phonic's network. The supplied headers are sent on every request Phonic makes to the server; their values are stored encrypted and never returned. Creating the server does not attach it to an agent; add its ID to an agent's `mcp_server_ids` to make its tools available.

Reference: https://docs.phonic.co/api-reference/mcp-servers/create

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).

## Request

### Query parameters

- `project` (string, optional, default: main) — The name of the project to create the MCP server in.

### Body (application/json)

This endpoint expects a CreateMcpServerRequest.

- `name` (string, required) — The name of the MCP server. Must be snake_case, start with a lowercase letter and be unique within the project.
- `url` (string, required) — The URL of the MCP server. Must be a publicly routable HTTPS URL without embedded credentials. Cannot be changed after creation.
- `headers` (map from string to string, optional, default: {}) — Headers sent on every request to the MCP server (e.g. for authentication). Header names must be unique (case-insensitive) and values cannot contain line breaks. Values are stored encrypted and never returned.

## Response

### 201

Success response

- `id` (string, required) — The ID of the created MCP server.
- `name` (string, required) — The name of the created MCP server.

## Errors

### 400 Bad Request Error

Invalid parameters, or Phonic could not connect to the MCP server and list its tools

- `error` (ValidationErrorError, required)
- `param_errors` (map from string to string, required) — Parameter-specific validation errors

### 401 Unauthorized Error

Unauthorized (authentication missing or invalid)

- `error` (BasicErrorError, optional)

### 404 Not Found Error

Project not found

- `error` (BasicErrorError, optional)

### 409 Conflict Error

MCP server name already exists

- `error` (ValidationErrorError, required)
- `param_errors` (map from string to string, required) — Parameter-specific validation errors

### 500 Internal Server Error

Internal server error

- `error` (BasicErrorError, optional)

## Types

### ValidationErrorError

- `message` (string, required) — Error message

### BasicErrorError

- `message` (string, required) — Error message
- `code` (string, optional) — Error code

## Examples

### Created MCP server response

**Response**

```json
{
  "id": "mcp_server_3f8b2c1d-6a4e-4b7f-9c2d-1e5a7b9c0d2f",
  "name": "crm_server"
}
```

**SDK Code**

```python Created MCP server response
import requests

url = "https://api.phonic.ai/v1/mcp_servers"

querystring = {"project":"main"}

headers = {"Authorization": "Bearer <apiKey>"}

response = requests.post(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Created MCP server response
const url = 'https://api.phonic.ai/v1/mcp_servers?project=main';
const options = {method: 'POST', headers: {Authorization: 'Bearer <apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Created MCP server response
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.phonic.ai/v1/mcp_servers?project=main"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Created MCP server response
require 'uri'
require 'net/http'

url = URI("https://api.phonic.ai/v1/mcp_servers?project=main")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'

response = http.request(request)
puts response.read_body
```

```java Created MCP server response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.phonic.ai/v1/mcp_servers?project=main")
  .header("Authorization", "Bearer <apiKey>")
  .asString();
```

```php Created MCP server response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.phonic.ai/v1/mcp_servers?project=main', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Created MCP server response
using RestSharp;

var client = new RestClient("https://api.phonic.ai/v1/mcp_servers?project=main");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Created MCP server response
import Foundation

let headers = ["Authorization": "Bearer <apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.phonic.ai/v1/mcp_servers?project=main")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### mcp_servers_create_example

**Request**

```json
{
  "name": "crm_server",
  "url": "https://mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer token123"
  }
}
```

**Response**

```json
{
  "id": "mcp_server_3f8b2c1d-6a4e-4b7f-9c2d-1e5a7b9c0d2f",
  "name": "crm_server"
}
```

**SDK Code**

```python mcp_servers_create_example
import requests

url = "https://api.phonic.ai/v1/mcp_servers"

querystring = {"project":"main"}

payload = {
    "name": "crm_server",
    "url": "https://mcp.example.com/mcp",
    "headers": { "Authorization": "Bearer token123" }
}
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript mcp_servers_create_example
const url = 'https://api.phonic.ai/v1/mcp_servers?project=main';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"name":"crm_server","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer token123"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go mcp_servers_create_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.phonic.ai/v1/mcp_servers?project=main"

	payload := strings.NewReader("{\n  \"name\": \"crm_server\",\n  \"url\": \"https://mcp.example.com/mcp\",\n  \"headers\": {\n    \"Authorization\": \"Bearer token123\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby mcp_servers_create_example
require 'uri'
require 'net/http'

url = URI("https://api.phonic.ai/v1/mcp_servers?project=main")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"crm_server\",\n  \"url\": \"https://mcp.example.com/mcp\",\n  \"headers\": {\n    \"Authorization\": \"Bearer token123\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java mcp_servers_create_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.phonic.ai/v1/mcp_servers?project=main")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"crm_server\",\n  \"url\": \"https://mcp.example.com/mcp\",\n  \"headers\": {\n    \"Authorization\": \"Bearer token123\"\n  }\n}")
  .asString();
```

```php mcp_servers_create_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.phonic.ai/v1/mcp_servers?project=main', [
  'body' => '{
  "name": "crm_server",
  "url": "https://mcp.example.com/mcp",
  "headers": {
    "Authorization": "Bearer token123"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp mcp_servers_create_example
using RestSharp;

var client = new RestClient("https://api.phonic.ai/v1/mcp_servers?project=main");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"crm_server\",\n  \"url\": \"https://mcp.example.com/mcp\",\n  \"headers\": {\n    \"Authorization\": \"Bearer token123\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift mcp_servers_create_example
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "crm_server",
  "url": "https://mcp.example.com/mcp",
  "headers": ["Authorization": "Bearer token123"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.phonic.ai/v1/mcp_servers?project=main")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```