AgentOps MCP

Instructions

Implementation Reference

• src/index.ts:234-292 (handler)

  Handler logic for the 'auth' tool: authenticates using provided or env API key, stores JWT token in server state, fetches project name for confirmation.

  case "auth": {
    const { api_key } = args as { api_key?: string };
  
    // Check if already authenticated
    if (serverState.isAuthenticated() && !api_key) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                success: true,
                message: "Already authenticated",
                source:
                  "Previously authenticated (likely from environment variable on startup)",
              },
              null,
              2,
            ),
          },
        ],
      };
    }
  
    // Try to get API key from environment first, then from parameter
    const actualApiKey = api_key || process.env["AGENTOPS_API_KEY"];
    if (!actualApiKey) {
      throw new Error(
        "No project API key available. Please provide a project API key.",
      );
    }
  
    const authResult = await authWithApiKey(actualApiKey);
    if (typeof authResult === "object" && "error" in authResult) {
      throw new Error(`Authentication failed: ${authResult.error}`);
    }
  
    // Store the JWT token in server state
    serverState.setJwtToken(authResult);
  
    const result = await makeAuthenticatedRequest(`/public/v1/project`);
    const name = result.name;
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              success: true,
              message: "Authentication successful",
              project: name,
            },
            null,
            2,
          ),
        },
      ],
    };
  }

• src/index.ts:165-180 (schema)

  Input schema definition for the 'auth' tool, as returned in ListTools response.

  {
    name: "auth",
    description:
      "Authorize using the AGENTOPS_API_KEY. If the API key is not provided and cannot be found in the directory, ask the user for the API key.",
    inputSchema: {
      type: "object",
      properties: {
        api_key: {
          type: "string",
          description:
            "AgentOps project API key (optional if AGENTOPS_API_KEY environment variable is set)",
        },
      },
      required: [],
    },
  },

• src/index.ts:162-226 (registration)

  Registration of the 'auth' tool via the ListToolsRequestSchema handler, including it in the tools list.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "auth",
          description:
            "Authorize using the AGENTOPS_API_KEY. If the API key is not provided and cannot be found in the directory, ask the user for the API key.",
          inputSchema: {
            type: "object",
            properties: {
              api_key: {
                type: "string",
                description:
                  "AgentOps project API key (optional if AGENTOPS_API_KEY environment variable is set)",
              },
            },
            required: [],
          },
        },
        {
          name: "get_trace",
          description: "Get trace information and metrics by trace_id.",
          inputSchema: {
            type: "object",
            properties: {
              trace_id: {
                type: "string",
                description: "Trace ID",
              },
            },
            required: ["trace_id"],
          },
        },
        {
          name: "get_span",
          description: "Get span information and metrics by span_id.",
          inputSchema: {
            type: "object",
            properties: {
              span_id: {
                type: "string",
                description: "Span ID",
              },
            },
            required: ["span_id"],
          },
        },
        {
          name: "get_complete_trace",
          description:
            "Reserved for explicit requests for COMPLETE or ALL data. Get complete trace information and metrics by trace_id.",
          inputSchema: {
            type: "object",
            properties: {
              trace_id: {
                type: "string",
                description: "Trace ID",
              },
            },
            required: ["trace_id"],
          },
        },
      ],
    };
  });

• src/index.ts:80-96 (helper)

  Helper function authWithApiKey that performs the actual API call to obtain JWT token from AgentOps.

  async function authWithApiKey(apiKey: string): Promise<string | ErrorResponse> {
    const data = { api_key: apiKey };
  
    try {
      const response: AxiosResponse = await axios.post(
        `${HOST}/public/v1/auth/access_token`,
        data,
      );
      const bearer = response.data?.bearer;
      if (!bearer) {
        throw new Error("No bearer token received from auth endpoint");
      }
      return bearer;
    } catch (error) {
      return { error: error instanceof Error ? error.message : String(error) };
    }
  }

• src/index.ts:25-49 (helper)

  ServerState class that manages the JWT token and provides auth headers and auth status checks.

  class ServerState {
    private jwtToken: string | null = null;
  
    setJwtToken(token: string): void {
      this.jwtToken = token;
    }
  
    getAuthHeaders(): AuthHeaders | null {
      if (!this.jwtToken) {
        return null;
      }
      return {
        Authorization: `Bearer ${this.jwtToken}`,
        "User-Agent": "agentops-mcp/0.3.5",
      };
    }
  
    isAuthenticated(): boolean {
      return this.jwtToken !== null;
    }
  
    clearAuth(): void {
      this.jwtToken = null;
    }
  }