Finish connecting an external MCP server

curl --request POST \
  --url https://api-dev.narrative.io/mcp-connections/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "state": "Yk8fQ2Zsb3dTdGF0ZQ"
}
'

import requests

url = "https://api-dev.narrative.io/mcp-connections/complete"

payload = { "state": "Yk8fQ2Zsb3dTdGF0ZQ" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({state: 'Yk8fQ2Zsb3dTdGF0ZQ'})
};

fetch('https://api-dev.narrative.io/mcp-connections/complete', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/mcp-connections/complete",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'state' => 'Yk8fQ2Zsb3dTdGF0ZQ'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api-dev.narrative.io/mcp-connections/complete"

	payload := strings.NewReader("{\n  \"state\": \"Yk8fQ2Zsb3dTdGF0ZQ\"\n}")

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

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/mcp-connections/complete")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"state\": \"Yk8fQ2Zsb3dTdGF0ZQ\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/mcp-connections/complete")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"state\": \"Yk8fQ2Zsb3dTdGF0ZQ\"\n}"

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

{
  "connection_id": "b3f1c2a4-5d6e-47f8-9a0b-1c2d3e4f5a6b",
  "server_url": "https://huggingface.co/mcp",
  "alias": "huggingface",
  "authorization_server": "https://huggingface.co",
  "status": "connected",
  "created_at": "2026-07-12T17:00:00Z",
  "updated_at": "2026-07-12T17:02:11Z",
  "expires_at": "2026-07-12T18:30:00Z"
}

{
  "type": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/invalid-tool-alias",
  "title": "Invalid Tool Alias",
  "status": 400,
  "detail": "invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): with_underscore",
  "instance": "/agents",
  "log_id": "1f6e5d4c-3b2a-1098-7654-3210fedcba98",
  "debug": null
}

{
  "type": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/invalid-tool-alias",
  "title": "Invalid Tool Alias",
  "status": 400,
  "detail": "invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): with_underscore",
  "instance": "/agents",
  "log_id": "1f6e5d4c-3b2a-1098-7654-3210fedcba98",
  "debug": null
}

MCP Connections

Finish connecting an external MCP server

Completes a connection started by POST /mcp-connections, after the user has consented and the authorization server has redirected their browser through GET /mcp-connections/callback.

The Narrative app calls this from its callback page, so normally you don’t call it yourself. It is part of the public API because the connection flow can also be driven by an integration that handles the redirect itself.

What this endpoint actually does

Looks up the authorization flow by state (400 if unknown or expired).
Checks the connection behind that flow belongs to the calling user (404 otherwise).
Exchanges the stored authorization code at the server’s token endpoint, with the flow’s PKCE code_verifier and the resource indicator.
Validates the new token with a tools/list call against the MCP server.
Stores the encrypted tokens, flips the connection to connected, and consumes the flow.

Returns the connection’s status view, the same shape as GET /mcp-connections/{id}.

Only the user who started the flow can complete it

The state is not enough. This endpoint requires a bearer token, and the connection must belong to that token’s company_id and user_id. A connection owned by someone else returns 404 — identical to a nonexistent one, so ids can’t be probed across users. That is what stops a state from being used to capture another user’s access token, and it is why the public callback only stores the code instead of exchanging it.

A failed exchange leaves the flow in place so it can be retried; a failed tools/list validation consumes it, since the token has already been issued.

Permission

agent_conversations resource with write verb.

Example

curl -X POST "$API/mcp-connections/complete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "Yk8fQ2Zsb3dTdGF0ZQ"}'

Common errors

Status	Cause
400	`state` is malformed, unknown, or expired
400	the callback has not delivered the authorization code yet
400	the token exchange with the authorization server failed
400	the new token failed the `tools/list` validation against the MCP server
404	the connection does not exist, or belongs to another user

POST

mcp-connections

complete

Finish connecting an external MCP server

curl --request POST \
  --url https://api-dev.narrative.io/mcp-connections/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "state": "Yk8fQ2Zsb3dTdGF0ZQ"
}
'

import requests

url = "https://api-dev.narrative.io/mcp-connections/complete"

payload = { "state": "Yk8fQ2Zsb3dTdGF0ZQ" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({state: 'Yk8fQ2Zsb3dTdGF0ZQ'})
};

fetch('https://api-dev.narrative.io/mcp-connections/complete', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/mcp-connections/complete",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'state' => 'Yk8fQ2Zsb3dTdGF0ZQ'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api-dev.narrative.io/mcp-connections/complete"

	payload := strings.NewReader("{\n  \"state\": \"Yk8fQ2Zsb3dTdGF0ZQ\"\n}")

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

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/mcp-connections/complete")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"state\": \"Yk8fQ2Zsb3dTdGF0ZQ\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/mcp-connections/complete")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"state\": \"Yk8fQ2Zsb3dTdGF0ZQ\"\n}"

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

{
  "connection_id": "b3f1c2a4-5d6e-47f8-9a0b-1c2d3e4f5a6b",
  "server_url": "https://huggingface.co/mcp",
  "alias": "huggingface",
  "authorization_server": "https://huggingface.co",
  "status": "connected",
  "created_at": "2026-07-12T17:00:00Z",
  "updated_at": "2026-07-12T17:02:11Z",
  "expires_at": "2026-07-12T18:30:00Z"
}

{
  "type": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/invalid-tool-alias",
  "title": "Invalid Tool Alias",
  "status": 400,
  "detail": "invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): with_underscore",
  "instance": "/agents",
  "log_id": "1f6e5d4c-3b2a-1098-7654-3210fedcba98",
  "debug": null
}

{
  "type": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/invalid-tool-alias",
  "title": "Invalid Tool Alias",
  "status": 400,
  "detail": "invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): with_underscore",
  "instance": "/agents",
  "log_id": "1f6e5d4c-3b2a-1098-7654-3210fedcba98",
  "debug": null
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for POST /mcp-connections/complete. The state identifies the authorization flow to finish; the authorization code itself is already held server-side and is never sent by the client.

state

string

required

The one-time state issued by POST /mcp-connections and forwarded to the app by GET /mcp-connections/callback. Consumed once the connection completes.

Maximum string length: 512

Example:

"Yk8fQ2Zsb3dTdGF0ZQ"

Response

Connection completed. Returns the status view, normally with status: connected and the access token's expires_at.

Status view of one connection. Deliberately credential-free — the registered client secret and the encrypted access/refresh tokens are never returned.

connection_id

string<uuid>

required

Example:

"b3f1c2a4-5d6e-47f8-9a0b-1c2d3e4f5a6b"

server_url

string<uri>

required

The external MCP server this connection targets.

Example:

"https://huggingface.co/mcp"

alias

string

required

Example:

"huggingface"

authorization_server

string<uri>

required

The OAuth issuer discovered for the server.

Example:

"https://huggingface.co"

status

enum<string>

required

Lifecycle. pending after creation, and while waiting on the user's consent and the completion call; connected once the token exchange succeeds and tools/list validates; error for a failed connection.

Available options:

pending,

connected,

error

Example:

"connected"

created_at

string<date-time>

required

Example:

"2026-07-12T17:00:00Z"

updated_at

string<date-time>

required

Example:

"2026-07-12T17:02:11Z"

expires_at

string<date-time> | null

When the current access token expires, if the server issued an expiry. The platform refreshes it automatically before use when a refresh token is available.

Example:

"2026-07-12T18:30:00Z"

⌘I