HubSpot MCP Server

Instructions

🔄 Refreshes the HubSpot OAuth access token using the refresh token from environment variables.

🎯 Purpose:
- Use only when HubSpot API requests fail due to expired tokens.
- Automatically refreshes and sets the active access token in process.env.PRIVATE_APP_ACCESS_TOKEN.
- Not required for long-lived Private App tokens.

🛡️ Guardrails:
- Only use if using OAuth (i.e. REFRESH_TOKEN is present in environment).
- Do not invoke more than once per session unless a 401 Unauthorized response is received from HubSpot API.

Implementation Reference

• dist/tools/oauth/refreshTokenTool.js:36-94 (handler)

  Executes the token refresh logic: validates environment variables, makes POST request to HubSpot OAuth endpoint, updates process.env.PRIVATE_APP_ACCESS_TOKEN on success, returns structured response.

  async process() {
    const { CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN } = process.env;
  
    if (!CLIENT_ID || !CLIENT_SECRET || !REFRESH_TOKEN) {
      return {
        content: [
          {
            type: 'text',
            text: '❌ Missing CLIENT_ID, CLIENT_SECRET, or REFRESH_TOKEN in environment.',
          },
        ],
        isError: true,
      };
    }
  
    try {
      const res = await fetch('https://api.hubapi.com/oauth/v1/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
          grant_type: 'refresh_token',
          client_id: CLIENT_ID,
          client_secret: CLIENT_SECRET,
          refresh_token: REFRESH_TOKEN,
        }),
      });
  
      const json = await res.json();
  
      if (!res.ok) {
        throw new Error(json.message || 'Token refresh failed');
      }
  
      process.env.PRIVATE_APP_ACCESS_TOKEN = json.access_token;
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              access_token: json.access_token,
              expires_in: json.expires_in,
              refresh_token: json.refresh_token,
            }, null, 2),
          },
        ],
      };
    } catch (err) {
      return {
        content: [
          {
            type: 'text',
            text: `❌ Token refresh failed: ${err instanceof Error ? err.message : String(err)}`,
          },
        ],
        isError: true,
      };
    }
  }

• dist/tools/toolsRegistry.js:48-48 (registration)

  Registers an instance of the RefreshTokenTool with the central tool registry.

  registerTool(new RefreshTokenTool());

• dist/tools/oauth/refreshTokenTool.js:5-29 (schema)

  Defines the Zod input schema (empty object, relies on env vars) and ToolDefinition object with name, description, JSON schema for inputs, and annotations passed to BaseTool constructor.

  const RefreshTokenSchema = z.object({}); // No inputs — uses environment variables
  
  const ToolDefinition = {
    name: 'hubspot-refresh-token',
    description: `
      🔄 Refreshes the HubSpot OAuth access token using the refresh token from environment variables.
  
      🎯 Purpose:
      - Use only when HubSpot API requests fail due to expired tokens.
      - Automatically refreshes and sets the active access token in process.env.PRIVATE_APP_ACCESS_TOKEN.
      - Not required for long-lived Private App tokens.
  
      🛡️ Guardrails:
      - Only use if using OAuth (i.e. REFRESH_TOKEN is present in environment).
      - Do not invoke more than once per session unless a 401 Unauthorized response is received from HubSpot API.
    `,
    inputSchema: zodToJsonSchema(RefreshTokenSchema),
    annotations: {
      title: 'Refresh HubSpot OAuth Token',
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false,
    },
  };