authbox

Instructions

Implementation Reference

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

  Handler function for 'proxy_authenticated_request' tool. Evaluates policies and calls bridge.proxyRequest.

  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 and input schema for 'proxy_authenticated_request'.

  {
    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:230-231 (registration)

  Registration of the tool within the handleToolCall method switch statement.

  case 'proxy_authenticated_request':
    return this.toolProxyRequest(session, policies, args);