Noteit MCP is an HTTP MCP server built on a Next.js API route. It exposes an endpoint at /api/mcp that enables AI tools to securely access two core systems: Agent Profiles and Notes. Agents can be configured with reusable profiles (personas, instructions, rules, documents) and used to manage notes with structured records and graph visualizations. Authentication supports OAuth 2.1 with device fingerprint for IDEs that support it, with an optional API Token flow for non-OAuth clients. This makes it easy for a variety of tooling to securely discover, instantiate, and use the profiles and note data provided by Noteit MCP.

Tools exposed by Noteit MCP include: noteit_profiles_list to list available agent profiles, noteit_profiles_getConfig to retrieve a composable AI agent configuration, noteit_profiles_generate to create individual configuration components, noteit_notes_create to add new notes (types include note, task, why, and issue), noteit_notes_read to fetch complete content of a note, noteit_notes_list to browse notes with filters, noteit_web_create to generate interactive HTML notes, and noteit_flow_create to render visual flow diagrams. These tools enable programmatic construction of agent behaviors and rich, visual note representations for development teams.

Prerequisites:

• Node.js (14+ or newer) and npm/yarn installed on your machine
• Git (optional for cloning the repo)

Installation steps:

1. Install the MCP package (replace with the actual repo or package name if different): npm install -g bahfahh-noteit-mcp

   or if you are building from source:

   git clone https://github.com/your-org/bahfahh-noteit-mcp.git cd bahfahh-noteit-mcp npm install

2. Configure environment (see notes on environment variables below):

   • Ensure any required OAuth credentials or API tokens are available as env vars or in a config file per the package’s guidance.

3. Run the server (default development mode): npm run dev

   or if you have a build step:

   npm run build npm start

4. Verify the MCP endpoint is reachable: curl -i http://localhost:3000/api/mcp

5. If you prefer a production-like run via npm scripts, ensure you set NODE_ENV=production before starting.

Notes and tips:

• The MCP endpoint is /api/mcp; use this as the base URL for all tool calls from compatible clients.
• OAuth 2.1 with device fingerprint is supported for IDEs that can present device-derived fingerprints. If your client does not support this, use the API Token flow by obtaining a token from the Noteit MCP site and passing it in the Authorization header as a Bearer token.
• When using noteit_notes_create or noteit_profiles_generate, organize assets with clear tags and project mappings to improve searchability in note lists.
• If you encounter authentication issues, ensure the system clock is synchronized, as OAuth flows can be sensitive to clock drift. Check firewall/proxy settings if external clients cannot reach the /api/mcp endpoint.
• For deployment, consider using a reverse proxy (e.g., Nginx) and enabling TLS to protect tokens and notes in transit.