proxy_authenticated_request

Instructions

Implementation Reference

• packages/mcp-protocol/src/server.ts:303-370 (handler)

  The main handler for the 'proxy_authenticated_request' tool. Method 'toolProxyRequest' evaluates policies (including step-up approval), constructs a ProxyRequest, and calls 'bridge.proxyRequest' to execute the authenticated HTTP request.

  private async toolProxyRequest(
    session: MCPSession,
    policies: AgentPolicy[],
    args: Record<string, unknown>,
  ): Promise<ToolCallResult> {
    const serviceName = args.service_name as string;
  
    const request: AccessRequest = {
      agentId: session.agentId,
      action: 'proxy',
    };
  
    const decision = this.policyEngine.evaluate(policies, request);
  
    // Handle step-up approval for proxy requests
    if (!decision.allowed && decision.pendingApprovalId) {
      const approved = await this.policyEngine.requestApproval(
        decision.pendingApprovalId,
        request,
      );
      if (!approved) {
        decision.reason = 'Step-up approval denied by user';
        await this.logAccess(session, 'proxy_request', serviceName, decision);
        return {
          content: [{ type: 'text', text: 'Access denied: step-up approval was denied by the user' }],
          isError: true,
        };
      }
      decision.allowed = true;
      decision.reason = 'Step-up approval granted by user';
    }
  
    await this.logAccess(session, 'proxy_request', serviceName, decision);
  
    if (!decision.allowed) {
      return {
        content: [{ type: 'text', text: `Access denied: ${decision.reason}` }],
        isError: true,
      };
    }
  
    const proxyReq: ProxyRequest = {
      method: args.method as string,
      url: args.url as string,
      headers: args.headers as Record<string, string> | undefined,
      body: args.body as string | undefined,
    };
  
    try {
      const response = await this.bridge.proxyRequest(session.userId, serviceName, proxyReq);
  
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            status: response.status,
            headers: response.headers,
            body: response.body,
          }),
        }],
      };
    } catch (err) {
      return {
        content: [{ type: 'text', text: `Proxy request failed: ${err instanceof Error ? err.message : 'Unknown error'}` }],
        isError: true,
      };
    }
  }

• packages/mcp-protocol/src/tools.ts:28-60 (schema)

  Tool definition (name, description, inputSchema) for 'proxy_authenticated_request'. Defines required input params: service_name, method, url; optional: headers, body.

  {
    name: 'proxy_authenticated_request',
    description:
      'Make an authenticated HTTP request through Auth Box. The stored credential is injected into the request without exposing it to the agent. This is the preferred method for using credentials.',
    inputSchema: {
      type: 'object',
      properties: {
        service_name: {
          type: 'string',
          description: 'Name of the service whose credential to use for authentication',
        },
        method: {
          type: 'string',
          enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
          description: 'HTTP method',
        },
        url: {
          type: 'string',
          description: 'Full URL to send the request to',
        },
        headers: {
          type: 'object',
          additionalProperties: { type: 'string' },
          description: 'Additional HTTP headers (auth headers are injected automatically)',
        },
        body: {
          type: 'string',
          description: 'Request body (for POST/PUT/PATCH)',
        },
      },
      required: ['service_name', 'method', 'url'],
    },
  },

• packages/mcp-protocol/src/server.ts:227-239 (registration)

  Tool dispatch registration in 'handleToolCall' switch statement: routes the tool name 'proxy_authenticated_request' to 'toolProxyRequest'.

  switch (toolName) {
    case 'get_credential':
      return this.toolGetCredential(session, policies, args);
    case 'proxy_authenticated_request':
      return this.toolProxyRequest(session, policies, args);
    case 'list_available_services':
      return this.toolListServices(session, policies);
    default:
      return {
        content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],
        isError: true,
      };
  }

• packages/mcp-protocol/src/tools.ts:72-88 (helper)

  Supporting types: ProxyRequest and ProxyResponse interfaces used by the proxy handler.

  export interface ProxyRequest {
    method: string;
    url: string;
    headers?: Record<string, string>;
    body?: string;
  }
  
  export interface ProxyResponse {
    status: number;
    headers: Record<string, string>;
    body: string;
  }
  
  export interface ToolCallResult {
    content: Array<{ type: 'text'; text: string }>;
    isError?: boolean;
  }

• packages/mcp-protocol/src/stdio-server.ts:27-40 (registration)

  Stdio server registration of 'proxy_authenticated_request' tool with Zod schema for MCP client discovery (fallback handler returning error if no vault bridge).

  server.tool(
    'proxy_authenticated_request',
    'Make an authenticated HTTP request through Auth Box. The stored credential is injected into the request without exposing it to the agent. This is the preferred method for using credentials.',
    {
      service_name: z.string().describe('Name of the service whose credential to use for authentication'),
      method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
      url: z.string().describe('Full URL to send the request to'),
      headers: z.record(z.string()).optional().describe('Additional HTTP headers (auth headers are injected automatically)'),
      body: z.string().optional().describe('Request body (for POST/PUT/PATCH)'),
    },
    async () => ({
      content: [{ type: 'text' as const, text: JSON.stringify({ error: 'Vault bridge not configured. Connect to a running Auth Box instance.' }) }],
    }),
  );