AI Apps and MCP

AI Apps lets MCP-compatible applications work with GitVault notes while GitVault Desktop remains the approval and permission authority.

What AI Apps can access

An app can receive only the note operations you enable: list metadata, read content, search, create, append, edit, archive, delete, and include archived notes. GitVault enforces these permissions inside the local server.

Available note tools are list_notes, search_notes, get_note, list_note_tags, create_note, append_to_note, update_note, archive_note, and delete_note.

Enable the local service

1. 1
   Install and open GitVault Desktop.

   Use the Windows, macOS, or Linux release. The web and Android apps do not host MCP.

2. 2
   Unlock the vault.

   MCP can connect while locked, but every note operation returns a locked error.

3. 3
   Open Settings, then AI Apps.

   Turn on Allow AI apps. The service binds only to the local loopback interface.

4. 4
   Choose lifecycle options.

   Enable launch at sign-in or Keep running in tray only when you want local AI apps available after closing the window.

Connect an AI app

1. 1
   Select Connect AI App.

   Give the connection a name you will recognize in approvals and activity history.

2. 2
   Select stdio or Streamable HTTP.

   Use the transport supported by the target application.

3. 3
   Select permissions and tag scope.

   Start with the smallest set required for the task.

4. 4
   Copy the generated configuration.

   Add it to the target application's MCP settings. HTTP credentials are shown only once; stdio configurations refer to a protected profile managed by Desktop.

5. 5
   Test while GitVault is unlocked.

   Ask the application to list note titles before granting write permissions.

Choose a transport

Do not paste an HTTP credential into chat, logs, issue reports, or a shared configuration repository. Rotate it from AI Apps if it may have been exposed.

Set permissions and tag scope

• Read metadata Allows titles, tags, note IDs, and timestamps without note bodies.
• Read content Allows full note bodies for notes inside the app scope.
• Search Allows bounded search results. It checks note bodies only when Read content is also enabled; otherwise it searches titles and tags and returns no content snippet.
• Write permissions Grant create, append, edit, archive, and delete separately.
• Allowed tags When empty, all notes are in scope unless denied. When set, a note must contain at least one allowed tag.
• Denied tags Always take priority over allowed tags.
• Archived notes Stay hidden unless Include archived notes is enabled.

Approve writes

The default write policy asks in GitVault Desktop. The approval shows the app, operation, note, and before/after content. Approvals expire after 60 seconds and are cancelled when the vault locks.

• Allow once Applies only that request.
• Always allow Exempts that write type for this app while the vault is unlocked.
• Deny Leaves the note unchanged.
• Delete Always requires explicit approval and never gains an always-allow exemption.

Updates use the note's modified_at timestamp. If the note changes while approval is pending, GitVault returns a conflict instead of replacing the newer edit.

Lock, rotate, or revoke

• Lock Immediately blocks note reads and writes without stopping the local listener.
• Rotate credential Invalidates the old credential and produces a replacement configuration.
• Revoke Disconnects that app and invalidates its credential.
• Remove Deletes the local registration and stdio profile.
• Quit GitVault Stops the MCP service. Closing to tray does not quit when Keep running in tray is enabled.

Recent activity is kept locally for 30 days, contains no note body or credential, and can be cleared from AI Apps.

Security boundary

The MCP endpoint is local-only, rejects browser origins, validates the host, rate-limits requests, and authenticates every request. Client registrations stay on this desktop and are not synchronized through GitHub.

The operating-system user account is the local trust boundary. Another process already running as the same compromised OS user may be able to impersonate a local AI application. GitVault does not claim to verify a third-party app's brand name.

Troubleshooting

• Desktop unavailable Open GitVault Desktop and confirm Allow AI apps is enabled.
• Vault locked Unlock in GitVault. MCP never opens a biometric or PIN prompt by itself.
• Unauthorized Rotate the app credential, replace its configuration, and reconnect.
• Permission denied Review that app's permissions and tag scope in AI Apps.
• Approval timeout Retry the write and answer the Desktop dialog within 60 seconds.
• Conflict Read the note again and retry using the newest modified_at.