@or-sdk/mcp-tools

The McpTools class provides methods for interacting with OneReach MCP (Model Context Protocol) infrastructure — listing internal MCP servers, discovering available packages, and handling OAuth authorization flows.

Installation

npm install @or-sdk/mcp-tools

Usage

Importing and Instantiating

import { McpTools } from '@or-sdk/mcp-tools';

const mcpTools = new McpTools({
  token: 'your-token',
  mcpApiUrl: 'https://mcp-api.example.com',
  mcpToolsUrl: 'https://mcp-tools-api.example.com',
});

Configuration

| Parameter | Type | Required | Description | |---|---|---|---| | token | string \| (() => string) | Yes | Authentication token or a getter function | | discoveryUrl | string | No | OneReach service discovery API URL | | mcpApiUrl | string | No | MCP internal API base URL (required for getInternalServers) | | mcpToolsUrl | string | No | MCP tools API base URL (required for getDiscovery) |

Methods

getInternalServers(options?)

Retrieves the list of internal MCP servers registered in the account.

Requires mcpApiUrl to be set.

const { servers, total } = await mcpTools.getInternalServers();

servers.forEach((server) => {
  console.log(server.name, server.url);
});

Returns: Promise<InternalServersResponse>

getDiscovery(options?)

Retrieves MCP discovery information — the list of available MCP packages with their URLs and auth types.

Requires mcpToolsUrl to be set.

const { packages } = await mcpTools.getDiscovery();

packages.forEach((pkg) => {
  console.log(pkg.package, pkg.auth);
});

Returns: Promise<DiscoveryResponse>

getAvailableMcp(options?)

Fetches both internal MCP servers and discovery packages in parallel and returns them as a single unified list. If only one URL is configured, the other source is silently skipped.

const { items, total } = await mcpTools.getAvailableMcp();

items.forEach((item) => {
  console.log(item.name, item.source, item.auth);
});

Each item in items has the shape:

| Field | Type | Description | |---|---|---| | name | string | Package or server name | | url | string | MCP endpoint URL | | auth | string | Auth type ('bearer', 'oauth', etc.) | | description | string? | Description (internal servers only) | | redirectUrl | string? | OAuth redirect URL (discovery packages only) | | source | 'internal' \| 'discovery' | Origin of the entry |

Returns: Promise<AvailableMcpResponse>

authorizeOAuthPackage(pkg)

Opens the OAuth authorization URL for a given package in a new browser window/tab.

import { McpTools, OAuthPackage } from '@or-sdk/mcp-tools';

const { items } = await mcpTools.getAvailableMcp();

const googleCalendar = items.find(
  (item) => item.name === 'google-calendar' && item.auth === 'oauth'
);

if (googleCalendar) {
  mcpTools.authorizeOAuthPackage(googleCalendar as OAuthPackage);
}

Returns: Window | null — the opened window reference, or null if blocked by the browser.

parseError(err)

Parses an error thrown by any API method into a structured OrNetworkError.

import { McpTools, isOrNetworkError } from '@or-sdk/mcp-tools';

try {
  await mcpTools.getInternalServers();
} catch (err) {
  const parsed = mcpTools.parseError(err);
  if (isOrNetworkError(parsed)) {
    console.error(parsed.status, parsed.message);
  }
}

Error Handling

Use the exported isOrNetworkError guard to narrow caught errors:

import { isOrNetworkError } from '@or-sdk/mcp-tools';

try {
  const result = await mcpTools.getDiscovery();
} catch (err) {
  const parsed = mcpTools.parseError(err);
  if (isOrNetworkError(parsed)) {
    console.error('Network error:', parsed.status, parsed.message);
  } else {
    throw err;
  }
}

You can also pass an AbortSignal to any method to support cancellation:

const controller = new AbortController();

const result = await mcpTools.getAvailableMcp({ signal: controller.signal });

// Cancel the request
controller.abort();

Additional API reference

Methods below were missing from the package guide. Signatures and return types are taken directly from the exported source API.

McpTools

| Method | Returns | Purpose | |---|---|---| | checkCredentials(sdkPackage: string, options: CallOptions = {}) | Promise<CheckCredentialsResponse> | Checks if OAuth credentials exist and are valid for the given SDK package. | | removeCredentials(sdkPackage: string, options: CallOptions = {}) | Promise<RemoveCredentialsResponse> | Removes stored OAuth credentials for the given SDK package. |

Exported utility reference

| Function | Returns | Purpose | |---|---|---| | createErrorParser(...processors: ErrorProcessor<E>[]) | unknown | Exported utility; see its TypeScript signature for behavior. | | parseAxiosError(e: AxiosError) | Error | Exported utility; see its TypeScript signature for behavior. | | isOrNetworkError(err: unknown) | err is OrNetworkError | Exported utility; see its TypeScript signature for behavior. |