Universal Tool Calling Protocol (UTCP) Code-Mode

To support tools requiring interactive sign-in, declare an oauth2_user auth block in your configuration. UTCP does not run the OAuth flow itself; instead, it provides the interface for the user to complete it.

Remote MCP Servers (e.g., Notion)

Use a minimal block where endpoints are auto-discovered via the MCP SDK. The token is injected using a variable placeholder:

"auth": { "auth_type": "oauth2_user", "access_token": "${NOTION_TOKEN}" }

To complete the login, run utcp login notion. This prints a sign-in URL. After authorizing, provide the redirect URL back via the --code flag.

HTTP APIs with Device-Code Flow

Declare the following keys in your auth block:

• device_authorization_endpoint
• token_endpoint
• client_id
• scope

Running utcp login <manual> will print a URL and a code, then poll until the user completes the flow.

Note: Tokens are written to the dotenv file (default .env), keyed by <manual>_<VAR>. You must include a dotenv loader block in your config to use these secrets.

You can execute TypeScript code that has direct access to UTCP tools by registering tool manuals and implementations using addFunctionToUtcpDirectCall, creating a CodeModeUtcpClient, and then calling callToolChain.

import { CodeModeUtcpClient } from '@utcp/code-mode';
import { addFunctionToUtcpDirectCall } from '@utcp/direct-call';

// 1. Register a function that returns a UTCP manual (describes the tool schema)
addFunctionToUtcpDirectCall('getWeatherManual', async () => ({
  utcp_version: '0.2.0',
  tools: [{
    name: 'get_current',
    description: 'Get current weather for a city',
    inputs: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city']
    },
    tool_call_template: {
      call_template_type: 'direct-call',
      callable_name: 'getWeather'
    }
  }]
}));

// 2. Register the actual tool implementation
addFunctionToUtcpDirectCall('getWeather', async (city: string) => ({
  city,
  temperature: 22,
  condition: 'sunny'
}));

// 3. Create client and register manual
const client = await CodeModeUtcpClient.create();
await client.registerManual({
  name: 'weather',
  call_template_type: 'direct-call',
  callable_name: 'getWeatherManual'
});

// 4. Execute code with tool access
const { result, logs } = await client.callToolChain(`
  const data = weather.get_current({ city: 'London' });
  console.log('Weather:', data);
  return data;
`);

console.log(result);
// { city: 'London', temperature: 22, condition: 'sunny' }

import { CodeModeUtcpClient } from '@utcp/code-mode';
import { addFunctionToUtcpDirectCall } from '@utcp/direct-call';

// Register a function that returns a UTCP manual
addFunctionToUtcpDirectCall('getWeatherManual', async () => ({
  utcp_version: '0.2.0',
  tools: [{
    name: 'get_current',
    description: 'Get current weather for a city',
    inputs: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city']
    },
    tool_call_template: {
      call_template_type: 'direct-call',
      callable_name: 'getWeather'
    }
  }]
}));

// Register the actual tool implementation
addFunctionToUtcpDirectCall('getWeather', async (city: string) => ({
  city,
  temperature: 22,
  condition: 'sunny'
}));

// Create client and register manual
const client = await CodeModeUtcpClient.create();
await client.registerManual({
  name: 'weather',
  call_template_type: 'direct-call',
  callable_name: 'getWeatherManual'
});

// Execute code with tool access
const { result, logs } = await client.callToolChain(`
  const data = weather.get_current({ city: 'London' });
  console.log('Weather:', data);
  return data;
`);

console.log(result);
// { city: 'London', temperature: 22, condition: 'sunny' }

To use Code Mode with an AI framework (like OpenAI or Anthropic), include the CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE in your system prompt. This template instructs the agent on the correct workflow for tool discovery and execution:

1. Discovery: Use searchTools(query) to find relevant tools.
2. Introspection: Use __interfaces and __getToolInterface() to understand tool schemas.
3. Execution: Use callToolChain(code) to run the logic.
4. Syntax: Use the manual.tool() hierarchical access pattern.

import { CodeModeUtcpClient } from '@utcp/code-mode';

const systemPrompt = `
You are an AI assistant with access to tools via UTCP CodeMode.
${CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE}
Additional instructions...
`;

// Works with any AI library
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: 'Analyze the latest PR in microsoft/vscode' }
  ]
});