Connect your AI Agents to OneNote in minutes
Available tools
list_notebooks
List the user's OneNote notebooks. Supports pagination with top/skip, sorting with orderby, and OData filtering. Expand 'sections' or 'sectionGroups' to include children.
get_notebook
Get a specific OneNote notebook by ID. Use list_notebooks to find valid notebook IDs. Expand 'sections' or 'sectionGroups' to include children.
create_notebook
Create a new OneNote notebook with the given display name. The name must be unique across the user's notebooks. Max 128 characters.
copy_notebook
Copy a OneNote notebook. This is an async operation - returns an operation URL to poll for status. Use list_notebooks to find valid notebook IDs.
get_recent_notebooks
Get a list of recently accessed OneNote notebooks, including notebooks from other users shared with the current user.
get_default_notebook
Get the user's default OneNote notebook. Returns the notebook marked as default, or the first notebook if none is marked as default.
list_pages
List OneNote pages in a specific section. Always requires section_id for performance (global page listing can fail). Use list_sections to find valid section IDs.
get_page
Get OneNote page metadata by ID (title, dates, links). Does NOT include content - use get_page_content for HTML body. Use list_pages to find valid page IDs.
get_page_content
Get the HTML content of a OneNote page. Set include_ids=true to get data-id attributes needed for PATCH updates. Use list_pages to find valid page IDs.
create_page
Create a new OneNote page in a section. Provide HTML content (e.g. 'Hello'). The title becomes the page heading. Use list_sections to find valid section IDs.
update_page
Update a OneNote page using PATCH operations. Each operation needs: target ('body' or element ID), action ('append','replace','prepend','insert'), content (HTML). Use get_page_content with include_ids=true to find element IDs.
delete_page
Delete a OneNote page permanently. This action cannot be undone. Use list_pages to find valid page IDs.
copy_page
Copy a OneNote page to a different section. Async operation - returns operation URL to poll. Use list_pages and list_sections to find valid IDs.
list_section_groups
List OneNote section groups. Filter by notebook_id to list groups in a specific notebook, or omit to list all section groups. Use list_notebooks to find valid IDs.
get_section_group
Get a specific OneNote section group by ID. Expand 'sections' or 'sectionGroups' to include children. Use list_section_groups to find valid IDs.
create_section_group
Create a new OneNote section group in a notebook. Section groups organize sections into folders. Use list_notebooks to find valid notebook IDs.
list_sections
List OneNote sections. Filter by notebook_id or section_group_id, or omit both to list all sections. Use list_notebooks to find valid notebook IDs.
get_section
Get a specific OneNote section by ID. Use list_sections to find valid section IDs. Expand 'pages' or 'parentNotebook' to include related data.
create_section
Create a new OneNote section in a notebook or section group. Provide either notebook_id or section_group_id. Use list_notebooks to find valid IDs.
copy_section_to_notebook
Copy a OneNote section to a different notebook. Async operation - returns operation URL. Use list_sections and list_notebooks to find valid IDs.
copy_section_to_section_group
Copy a OneNote section to a section group. Async operation - returns operation URL. Use list_sections and list_section_groups to find valid IDs.
validate_credential
Validate OneNote credentials. Verifies credentials during setup.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's OneNote MCP server
FAQs on using Merge's OneNote MCP server
What is a OneNote MCP?
A OneNote MCP is an MCP server that connects your agents to Microsoft OneNote via tools. Your agents can invoke these tools to create notebooks and sections, write and update pages, retrieve page content, and organize notes programmatically, and more.
Microsoft doesn't offer an MCP server purpose built for OneNote, but you can use one from a third-party platform, like Merge Agent Handler.
How can I use the OneNote MCP server?
The use cases naturally depend on the agent you've built, but here are a few common ones:
- Meeting notes automation: An agent receives a meeting transcript, structures it into action items and decisions, and creates a new OneNote page in the designated team section without any manual copy-paste step
- Resolved ticket documentation: When a support ticket is closed in a ticketing system, an agent creates a OneNote page capturing the issue, root cause, and resolution steps so the team has a searchable internal reference
- Research aggregation: An agent pulls content from multiple sources, synthesizes key findings, and writes a structured summary into a OneNote page so stakeholders have a single place to review the output
- Onboarding content generation: When a new team member is added in an HR system, an agent creates a personalized OneNote section populated with relevant onboarding pages, links, and checklists for their role
What are popular tools for OneNote's MCP server?
Here are some of the most commonly used tools:
create_page: creates a new page in a specified OneNote section with HTML content. Use this when an agent needs to write structured notes, a summary, or generated output into OneNote as part of a larger workflow
get_page_content: retrieves the full HTML content of a OneNote page. Call this when an agent needs to read an existing note before updating it, extracting information, or passing its contents to another tool
list_pages: returns all pages in a section with title and metadata. Helpful when an agent needs to find the right page before reading or modifying it, especially in sections with many entries
update_page: modifies the content of an existing OneNote page using PATCH-based element targeting. Good for agents that append new entries to a running log or update a specific section of a structured note
create_section: adds a new section to a notebook. Use this when an agent is setting up a structured workspace for a project, team, or recurring workflow that needs its own dedicated area
list_notebooks: returns all notebooks accessible to the authenticated user. Call this when an agent needs to locate the right notebook before navigating to a section or page within it
What makes Merge Agent Handler's OneNote MCP server better than alternative OneNote MCP servers?
A few things distinguish Merge Agent Handler's OneNote MCP server from community alternatives or a self-hosted implementation:
- Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For OneNote, this means you can prevent confidential meeting notes, personal data, and internal documentation from being exposed even when the agent has broad read access across notebooks
- Managed authentication and credentials: Merge stores and refreshes OneNote credentials on your behalf. You never expose raw OAuth tokens or Microsoft Graph API keys to an agent or manage token refresh cycles manually
- Real-time observability and audit trail: Every tool call made against OneNote is logged with timestamp, tool name, input parameters, and response metadata. You can see exactly what an agent read, created, or modified without instrumenting anything yourself
- Tool Packs and controlled access: Tool Packs let you bundle specific OneNote tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent that only writes meeting notes doesn't need access to notebook creation or section restructuring tools
How can I start using Merge Agent Handler's OneNote MCP server?
You can take the following steps:
1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).
2. Create a new Tool Pack, then find and enable the OneNote connector. Choose which tools to include: enable read tools for content retrieval use cases, or add write tools if your agent needs to create pages, update notes, or organize notebooks and sections.
3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.
4. From the Registered User detail page, authenticate OneNote by completing the OAuth flow. Merge stores and manages the credentials going forward.
5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.
6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your OneNote tools are now accessible through that endpoint.
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
