API MCP Server

Instructions

Implementation Reference

• src/index.ts:779-796 (handler)

  The handler logic for the 'get' tool within the CallToolRequestSchema handler. It extracts URL and optional headers/auth, performs the GET request via makeHttpRequest, and formats the response as text content.
  case "get": { const url = String(args?.url || ''); const auth = args?.auth as AuthConfig | undefined; const headers = applyAuthHeader(args?.headers as Record<string, string> || {}, auth); if (!url) { throw new Error("URL is required for GET request"); } const result = await makeHttpRequest('GET', { url, headers }); return { content: [{ type: "text", text: `GET ${url}\nStatus: ${result.status} ${result.statusText}\nResponse: ${JSON.stringify(result.data, null, 2)}` }] }; }
• src/index.ts:65-99 (schema)

  The schema definition for the 'get' tool, including name, description, and inputSchema with properties for url (required), headers, and auth.
  { name: "get", description: "Make a GET HTTP request", inputSchema: { type: "object", properties: { url: { type: "string", description: "The URL to make the GET request to" }, headers: { type: "object", description: "Optional headers to include in the request", additionalProperties: { type: "string" } }, auth: { type: "object", description: "Optional auth configuration to load a stored bearer token", properties: { folder: { type: "string", description: "Folder where tokens are stored (tokens.json)" }, user_title: { type: "string", description: "User title to pick the token from storage (default: 'default')" } } } }, required: ["url"] } },
• src/index.ts:62-333 (registration)

  Registration of the 'get' tool (among others) in the ListToolsRequestSchema handler, which lists all available tools.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "get", description: "Make a GET HTTP request", inputSchema: { type: "object", properties: { url: { type: "string", description: "The URL to make the GET request to" }, headers: { type: "object", description: "Optional headers to include in the request", additionalProperties: { type: "string" } }, auth: { type: "object", description: "Optional auth configuration to load a stored bearer token", properties: { folder: { type: "string", description: "Folder where tokens are stored (tokens.json)" }, user_title: { type: "string", description: "User title to pick the token from storage (default: 'default')" } } } }, required: ["url"] } }, { name: "post", description: "Make a pOST HTTP request", inputSchema: { type: "object", properties: { url: { type: "string", description: "The URL to make the POST request to" }, headers: { type: "object", description: "Optional headers to include in the request", additionalProperties: { type: "string" } }, body: { description: "The request body (JSON object, string, etc.)" }, requestType: { type: "string", enum: ["json", "form-data"], description: "Request type: 'json' for JSON data, 'form-data' for form data with file uploads" }, fieldFiles: { type: "array", items: { type: "string" }, description: "Array of field names that should be treated as files. Values can be URLs (http/https) for remote files or local file paths for local files. The system will automatically download remote files or read local files and include them as file attachments in the form data." }, auth: { type: "object", description: "Optional auth configuration to load a stored bearer token", properties: { folder: { type: "string", description: "Folder where tokens are stored (tokens.json)" }, user_title: { type: "string", description: "User title to pick the token from storage (default: 'default')" } } } }, required: ["url"] } }, { name: "put", description: "Make a PUT HTTP request", inputSchema: { type: "object", properties: { url: { type: "string", description: "The URL to make the PUT request to" }, headers: { type: "object", description: "Optional headers to include in the request", additionalProperties: { type: "string" } }, body: { description: "The request body (JSON object, string, etc.)" }, requestType: { type: "string", enum: ["json", "form-data"], description: "Request type: 'json' for JSON data, 'form-data' for form data with file uploads" }, fieldFiles: { type: "array", items: { type: "string" }, description: "Array of field names that should be treated as files. Values can be URLs (http/https) for remote files or local file paths for local files. The system will automatically download remote files or read local files and include them as file attachments in the form data." }, auth: { type: "object", description: "Optional auth configuration to load a stored bearer token", properties: { folder: { type: "string", description: "Folder where tokens are stored (tokens.json)" }, user_title: { type: "string", description: "User title to pick the token from storage (default: 'default')" } } } }, required: ["url"] } }, { name: "delete", description: "Make a DELETE HTTP request", inputSchema: { type: "object", properties: { url: { type: "string", description: "The URL to make the DELETE request to" }, headers: { type: "object", description: "Optional headers to include in the request", additionalProperties: { type: "string" } }, auth: { type: "object", description: "Optional auth configuration to load a stored bearer token", properties: { folder: { type: "string", description: "Folder where tokens are stored (tokens.json)" }, user_title: { type: "string", description: "User title to pick the token from storage (default: 'default')" } } } }, required: ["url"] } }, { name: "auth_login", description: "Authenticate against an API, extract a JWT, and store it locally for reuse", inputSchema: { type: "object", properties: { url: { type: "string", description: "The URL to make the authentication request to" }, headers: { type: "object", description: "Optional headers to include in the auth request", additionalProperties: { type: "string" } }, body: { description: "The request body for authentication" }, requestType: { type: "string", enum: ["json", "form-data"], description: "Request type for the auth call" }, fieldFiles: { type: "array", items: { type: "string" }, description: "Array of field names that should be treated as files for form-data auth requests" }, jwtPath: { type: "string", description: "Dot-notation path to the JWT in the response (e.g., token.access_token)" }, folder: { type: "string", description: "Folder where the token file will be stored" }, user_title: { type: "string", description: "Optional label for the stored token (default: 'default')" } }, required: ["url", "jwtPath", "folder"] } }, { name: "list_user", description: "List stored users and tokens from a token store", inputSchema: { type: "object", properties: { folder: { type: "string", description: "Folder where the token file is stored" }, file: { type: "string", description: "Optional token file name (default: tokens.json)" }, titlesOnly: { type: "boolean", description: "Return only user titles instead of full token entries" } }, required: ["folder"] } }, { name: "clear_user", description: "Remove a specific user or clear the token store", inputSchema: { type: "object", properties: { folder: { type: "string", description: "Folder where the token file is stored" }, file: { type: "string", description: "Optional token file name (default: tokens.json)" }, user_title: { type: "string", description: "Specific user title to remove. If omitted, all users are removed." }, preserveDefault: { type: "boolean", description: "When clearing all users, keep the 'default' user entry if it exists" } }, required: ["folder"] } } ] }; });
• src/index.ts:662-770 (helper)

  Core helper function called by the 'get' handler to execute the actual HTTP GET request with full fetch logic, body handling, etc.
  async function makeHttpRequest(method: string, config: HttpRequestConfig) { try { server.sendLoggingMessage({ level: "info", data: `Starting ${method.toUpperCase()} request to: ${config.url}`, }); const options: NodeRequestInit = { method: method.toUpperCase(), headers: { ...config.headers, }, }; if (config.body && (method === 'POST' || method === 'PUT')) { if (config.requestType === 'form-data') { server.sendLoggingMessage({ level: "info", data: `Using form-data request type with fieldFiles: ${JSON.stringify(config.fieldFiles)}`, }); // Use FormData for form-data requests const formData = await createFormData(config.body, config.fieldFiles); options.body = formData as any; // Cast to any to handle type incompatibility server.sendLoggingMessage({ level: "info", data: `FormData prepared, not setting Content-Type header (will be auto-set with boundary)`, }); // Don't set Content-Type header for FormData, let the system set it with boundary } else { server.sendLoggingMessage({ level: "info", data: `Using JSON request type`, }); // Use JSON for regular requests options.headers = { 'Content-Type': 'application/json', ...options.headers, }; options.body = typeof config.body === 'string' ? config.body : JSON.stringify(config.body); server.sendLoggingMessage({ level: "info", data: `JSON body prepared: ${options.body}`, }); } } else if (!config.body && method !== 'GET' && method !== 'DELETE') { // Set default Content-Type for POST/PUT without body options.headers = { 'Content-Type': 'application/json', ...options.headers, }; } server.sendLoggingMessage({ level: "info", data: `Request headers: ${JSON.stringify(options.headers)}`, }); server.sendLoggingMessage({ level: "info", data: `Making HTTP request...`, }); const response = await fetch(config.url, options); server.sendLoggingMessage({ level: "info", data: `Response received: ${response.status} ${response.statusText}`, }); const responseText = await response.text(); server.sendLoggingMessage({ level: "info", data: `Response body: ${responseText}`, }); // Try to parse as JSON, fallback to text let responseData; try { responseData = JSON.parse(responseText); } catch { responseData = responseText; } // Store in history requestHistory.push({ method: method.toUpperCase(), config, timestamp: new Date() }); return { status: response.status, statusText: response.statusText, headers: Object.fromEntries(response.headers.entries()), data: responseData }; } catch (error) { server.sendLoggingMessage({ level: "error", data: `HTTP ${method.toUpperCase()} request failed: ${error instanceof Error ? error.message : String(error)}`, }); throw new Error(`HTTP ${method.toUpperCase()} request failed: ${error instanceof Error ? error.message : String(error)}`); } }
• src/index.ts:418-444 (helper)

  Helper function used in 'get' handler to apply stored authentication tokens as Bearer headers.
  function applyAuthHeader(headers: Record<string, string>, auth?: AuthConfig): Record<string, string> { if (!auth) { return headers; } const folder = auth.folder; if (!folder) { throw new Error("auth.folder is required when using auth configuration"); } if (headers.Authorization) { return headers; } const userTitle = auth.user_title || 'default'; const tokens = loadStoredTokens(folder); const tokenEntry = tokens.find((entry) => entry.user_title_name === userTitle); if (!tokenEntry) { throw new Error(`No token found for user_title '${userTitle}' in folder '${folder}'`); } return { ...headers, Authorization: `Bearer ${tokenEntry.token}`, }; }