API Request Example

Learn how to make API requests to MCP server tools

Assumptions:

1. You have already obtained an access token from your user

2. Your access token has access to the necessary scopes to make API requests

Introduction

BlueNexus provides a proxy API for interacting with Model Context Protocol (MCP) servers. MCP servers expose tools, resources, and prompts that can be accessed by your application.

Key Features:

• RESTful API over HTTP

• Public access for listing MCP servers

• Authenticated access for tool operations

• Support for multiple MCP servers (Google Workspace, Notion, Slack, and more)

List Available MCP Servers

List all MCP servers available through BlueNexus. This endpoint supports both public and authenticated access.

Public Access (No Token Required)

Returns basic information about available MCP servers:

// Import dependencies
import fetch from "node-fetch";

// No authentication required for basic server list
const response = await fetch("https://api.bluenexus.ai/api/v1/mcps");
const data = await response.json();

console.log("Available MCP servers:");
for (const server of data.data) {
  console.log(`- ${server.slug}: ${server.label}`);
  console.log(`  URL: ${server.url}`);
}

// Example response:
// {
//   "data": [
//     {
//       "slug": "google-workspace",
//       "label": "Google Workspace",
//       "url": "https://api.bluenexus.ai/api/v1/mcps/google-workspace"
//     },
//     {
//       "slug": "notion",
//       "label": "Notion",
//       "url": "https://api.bluenexus.ai/api/v1/mcps/notion"
//     },
//     {
//       "slug": "slack",
//       "label": "Slack",
//       "url": "https://api.bluenexus.ai/api/v1/mcps/slack"
//     }
//   ],
//   "pagination": {
//     "page": 1,
//     "limit": 20,
//     "total": 9,
//     "pages": 1,
//     "hasNext": false,
//     "hasPrev": false
//   }
// }

Authenticated Access (With Token)

Returns additional information including activation status and full URLs:

// Import dependencies
import fetch from "node-fetch";

// Use access token for full details
const response = await fetch("https://api.bluenexus.ai/api/v1/mcps", {
  headers: {
    Authorization: `Bearer ${YourAccessToken}`,
  },
});

const data = await response.json();

console.log("Available MCP servers:");
for (const server of data.data) {
  console.log(`- ${server.slug}: ${server.label}`);
  console.log(`  Active: ${server.isActive}`);
  console.log(`  URL: ${server.url}`);
}

// Example response:
// {
//   "data": [
//     {
//       "slug": "google-workspace",
//       "label": "Google Workspace",
//       "isActive": true,
//       "url": "https://api.bluenexus.ai/api/v1/mcps/google-workspace"
//     },
//     {
//       "slug": "notion",
//       "label": "Notion",
//       "isActive": true,
//       "url": "https://api.bluenexus.ai/api/v1/mcps/notion"
//     },
//     {
//       "slug": "slack",
//       "label": "Slack",
//       "isActive": true,
//       "url": "https://api.bluenexus.ai/api/v1/mcps/slack"
//     }
//   ],
//   "pagination": {
//     "page": 1,
//     "limit": 20,
//     "total": 8,
//     "pages": 1,
//     "hasNext": false,
//     "hasPrev": false
//   }
// }

List Tools from an MCP Server

Retrieve all available tools from a specific MCP server. Requires authentication.

Example: Google Workspace Tools

// Import dependencies
import fetch from "node-fetch";

// Get tools from Google Workspace MCP server
const response = await fetch(
  "https://api.bluenexus.ai/api/v1/mcps/google-workspace/tools",
  {
    headers: {
      Authorization: `Bearer ${YourAccessToken}`,
    },
  }
);

const data = await response.json();

console.log("Google Workspace tools:");
for (const tool of data.tools) {
  console.log(`\n- ${tool.name}`);
  console.log(`  Description: ${tool.description}`);
  if (tool.inputSchema.required) {
    console.log(`  Required params: ${tool.inputSchema.required.join(", ")}`);
  }
}

// Example response (showing a subset of available tools):
// {
//   "tools": [
//     {
//       "name": "gmail_list_labels",
//       "description": "List all Gmail labels",
//       "inputSchema": {
//         "type": "object",
//         "properties": {}
//       }
//     },
//     {
//       "name": "gmail_search_messages",
//       "description": "Search Gmail messages",
//       "inputSchema": {
//         "type": "object",
//         "properties": {
//           "query": {
//             "type": "string",
//             "description": "Gmail search query"
//           },
//           "max_results": {
//             "type": "integer",
//             "description": "Maximum results (default: 10)",
//             "default": 10
//           }
//         }
//       }
//     },
//     {
//       "name": "drive_list_files",
//       "description": "List Google Drive files",
//       "inputSchema": {
//         "type": "object",
//         "properties": {
//           "query": {
//             "type": "string",
//             "description": "Search query for file names"
//           },
//           "max_results": {
//             "type": "integer",
//             "description": "Maximum results (default: 10)",
//             "default": 10
//           }
//         }
//       }
//     },
//     {
//       "name": "calendar_create_event",
//       "description": "Create a Google Calendar event",
//       "inputSchema": {
//         "type": "object",
//         "properties": {
//           "summary": {
//             "type": "string",
//             "description": "Event title"
//           },
//           "start_time": {
//             "type": "string",
//             "description": "Start time (ISO format)"
//           },
//           "end_time": {
//             "type": "string",
//             "description": "End time (ISO format)"
//           }
//         },
//         "required": ["summary", "start_time", "end_time"]
//       }
//     }
//   ]
// }

Example: Notion Tools

// Import dependencies
import fetch from "node-fetch";

// Get tools from Notion MCP server
const response = await fetch(
  "https://api.bluenexus.ai/api/v1/mcps/notion/tools",
  {
    headers: {
      Authorization: `Bearer ${YourAccessToken}`,
    },
  }
);

const data = await response.json();

console.log("Notion tools:");
for (const tool of data.tools) {
  console.log(`- ${tool.name}: ${tool.description}`);
}

// Example response (showing key tool):
// {
//   "tools": [
//     {
//       "name": "notion-search",
//       "title": "Search Notion and connected sources",
//       "description": "Perform a search over:\n- \"internal\": Semantic search over Notion workspace. Supports filtering by creation date and creator.\n- \"user\": Search for users by name or email.",
//       "inputSchema": {
//         "type": "object",
//         "properties": {
//           "query": {
//             "type": "string",
//             "minLength": 1,
//             "description": "Semantic search query over your entire Notion workspace and connected sources"
//           },
//           "query_type": {
//             "type": "string",
//             "enum": ["internal", "user"]
//           },
//           "filters": {
//             "type": "object",
//             "properties": {
//               "created_date_range": {
//                 "type": "object",
//                 "properties": {
//                   "start_date": { "type": "string", "format": "date" },
//                   "end_date": { "type": "string", "format": "date" }
//                 }
//               },
//               "created_by_user_ids": {
//                 "type": "array",
//                 "items": { "type": "string" }
//               }
//             }
//           }
//         },
//         "required": ["query"]
//       }
//     }
//   ]
// }

Call an MCP Server Tool

Execute a tool on an MCP server. Requires authentication.

Example: List Gmail Labels (Google Workspace)

// Import dependencies
import fetch from "node-fetch";

// Call the gmail_list_labels tool
const response = await fetch(
  "https://api.bluenexus.ai/api/v1/mcps/google-workspace/tools/gmail_list_labels",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${YourAccessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      arguments: {},
    }),
  }
);

const data = await response.json();

// Extract the tool result
const result = JSON.parse(data.content[0].text);
console.log("Gmail labels:");
for (const label of result.labels) {
  console.log(`- ${label.name} (${label.type})`);
}

// Example response:
// {
//   "content": [
//     {
//       "type": "text",
//       "text": "{\"success\": true, \"labels\": [{\"id\": \"INBOX\", \"name\": \"INBOX\", \"type\": \"system\"}, {\"id\": \"SENT\", \"name\": \"SENT\", \"type\": \"system\"}, {\"id\": \"DRAFT\", \"name\": \"DRAFT\", \"type\": \"system\"}]}"
//     }
//   ],
//   "isError": false
// }

Example: Search Notion Workspace

// Import dependencies
import fetch from "node-fetch";

// Call the notion-search tool
const response = await fetch(
  "https://api.bluenexus.ai/api/v1/mcps/notion/tools/notion-search",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${YourAccessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      arguments: {
        query: "project updates",
        query_type: "internal",
        filters: {
          created_date_range: {
            start_date: "2024-09-01",
          },
        },
      },
    }),
  }
);

const data = await response.json();

// Extract the tool result
const result = JSON.parse(data.content[0].text);
console.log("Search results:");
for (const item of result.results) {
  console.log(`\n- ${item.title}`);
  console.log(`  URL: ${item.url}`);
  console.log(`  Type: ${item.type}`);
  console.log(`  Updated: ${item.timestamp}`);
}

// Example response:
// {
//   "content": [
//     {
//       "type": "text",
//       "text": "{\"results\": [{\"title\": \"Q4 Planning\", \"url\": \"https://www.notion.so/...\", \"type\": \"page\", \"highlight\": \"Project roadmap updates\", \"timestamp\": \"2 days ago\"}], \"type\": \"ai_search\"}"
//     }
//   ]
// }

Example: Create Calendar Event (Google Workspace)

// Import dependencies
import fetch from "node-fetch";

// Call the calendar_create_event tool
const response = await fetch(
  "https://api.bluenexus.ai/api/v1/mcps/google-workspace/tools/calendar_create_event",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${YourAccessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      arguments: {
        summary: "Team Standup",
        start_time: "2024-12-15T10:00:00Z",
        end_time: "2024-12-15T10:30:00Z",
      },
    }),
  }
);

const data = await response.json();
const result = JSON.parse(data.content[0].text);
console.log("Event created:");
console.log(`- Event ID: ${result.event_id}`);
console.log(`- Link: ${result.html_link}`);

Authentication Requirements

Endpoint	Authentication Required	Returns
GET /api/v1/mcps	No (optional)	Public: slug, label, url Authenticated: slug, label, isActive, url
GET /api/v1/mcps/{serverId}/tools	Yes	List of available tools
POST /api/v1/mcps/{serverId}/tools/{toolName}	Yes	Tool execution result