> ## Documentation Index > Fetch the complete documentation index at: https://doc.askmydocs.padosoft.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect AI tools to a project > Connect Codex, Claude, Cursor and compatible MCP clients with OAuth, one project per connection, and document ingestion. AskMyDocs can serve as the project knowledge source for Codex, Claude Code, Claude web/Desktop, Cursor and compatible MCP clients. Each connection authorizes **one company and one project**, selected in the browser during OAuth consent. Another project gets another connection, plugin identity and MCP URL. You never copy API tokens, client IDs or secrets into the project. ## Install and connect Codex Open `/mcp/connect` on your AskMyDocs installation. Sign in, prepare a connection and download its plugin ZIP. Upload it in Codex under **Plugins > New plugin**. The archive contains `plugin.json`, `mcp.json`, `.codex-plugin/plugin.json`, `.mcp.json` and `skills/` directly at the plugin root. It does not contain a marketplace catalog or an outer `plugin/` directory. A marketplace archive is not a single-plugin upload. Operators can instead generate a local marketplace directory (a separate distribution format, not the ZIP upload): ```bash theme={null} php artisan askmydocs:mcp:plugin --output=/absolute/path/to/new-marketplace codex plugin marketplace add /absolute/path/to/new-marketplace ``` In Codex, choose the plugin and **Connect**. OAuth opens AskMyDocs, where you sign in, select a company, select one project in that company, and approve the requested permissions. A single available company or project is preselected. An existing connection remains bound to its original project on reauthorization. Start a **new chat/session** after installing a local plugin so its bundled tools are loaded. Installation alone does not prove the account has authorized access. The browser login happens on AskMyDocs; Codex receives and stores the resulting OAuth tokens. Never enter an AskMyDocs password into a chat. For a direct Codex CLI connection, expand **Connect through the Codex CLI** on the setup page and copy the generated commands: ```bash theme={null} codex mcp add askmydocs-CONNECTION-UUID --url 'https://YOUR-ASKMYDOCS/mcp/knowledge/CONNECTION-UUID' codex mcp login askmydocs-CONNECTION-UUID ``` The login command opens or repeats the OAuth flow for that directly configured server. See the official [Codex MCP commands](https://learn.chatgpt.com/docs/extend/mcp#other-cli-commands) and [plugin installation guide](https://learn.chatgpt.com/docs/plugins#install-and-use-a-plugin). Clients that support adding an HTTP MCP server directly can use the unique URL shown by the setup page instead of installing the package. No bearer-token configuration is needed. The endpoint is: ```text theme={null} https://YOUR-ASKMYDOCS/mcp/knowledge/CONNECTION-UUID ``` The local marketplace is for local Codex clients. A public listing in the ChatGPT/Codex universal plugin directory requires submitting the deployed HTTPS MCP server through OpenAI's plugin publishing and review flow; creating a local package does not publish it. A Herd `.test` endpoint is reachable from the local Mac, not from ChatGPT cloud execution. ## Connect Claude and other clients Open `/mcp/connect`, select the application, and prepare a connection. The page shows the unique URL and instructions for that client. Changing the application selector only changes instructions; OAuth identifies and authorizes the actual client. Prepare another connection for a different project. Separate connections per application also let you revoke each application's access independently. ### Claude web and Desktop In Claude, open **Customize > Connectors > Add > Custom > Web**. Enter a name and the connection's MCP URL. Choose **Sign in now** and **Register automatically** under OAuth client. AskMyDocs supports dynamic client registration; it does not currently support Claude's published-identity/CIMD option. No manual client ID, client secret, bearer token or request header is required. Finish browser sign-in and select the company/project in AskMyDocs. These custom connectors connect from **Anthropic's cloud**, including when used in Claude Desktop. They require a deployed public HTTPS AskMyDocs origin; the development address `https://askmydocsdev.test` is not reachable by Anthropic. See [Claude's connector setup](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities) and [network requirements](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). ### Claude Code Run the command generated by `/mcp/connect` in your development project: ```bash theme={null} claude mcp add --transport http askmydocs-CONNECTION-UUID 'https://YOUR-ASKMYDOCS/mcp/knowledge/CONNECTION-UUID' ``` Then open `/mcp` in Claude Code and complete OAuth sign-in. The generated server name includes the connection UUID, so a second project has a different name as well as a different URL. A local installation requires that the machine running Claude Code can resolve the Herd domain and trust its TLS certificate. See [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp). ### Cursor and other MCP clients Select **Cursor** to copy a ready-to-use `mcpServers` JSON entry, with a unique server name and URL. Merge it into Cursor's MCP configuration while preserving other servers, then enable the server and finish OAuth sign-in. Cursor supports [Streamable HTTP and OAuth](https://cursor.com/docs/mcp). Other clients need **Streamable HTTP, protected-resource OAuth discovery and dynamic client registration**. Use the connection URL, then complete browser sign-in. Clients supporting only local stdio or fixed bearer-token authentication cannot use this OAuth endpoint directly. The same search, read and ingest tools are exposed in every client. A client's ability to send local files or attachments depends on its file-access features; the ingest tool accepts file content, not a path on the user's computer. Server tests cover registration, PKCE, consent, token exchange and project reads with HTTPS, IPv4, IPv6 and exact `localhost` callbacks, including changing local ports and rejecting host/path/query substitutions. UI tests cover the client instructions and generated configurations. These tests do **not** claim that a real Claude or Cursor account has completed sign-in; that requires the deployed origin and an end-to-end check in the chosen client. ## Search and read The connected server exposes these tools: | Tool | Purpose | | - | - | | `kb-connected-project-tool` | Identify the authorized company, project and scopes. | | `kb-connected-search-tool` | Search that project and return source identifiers and bounded text. | | `kb-connected-document-tool` | Read one authorized document, with chunk pagination. | | `kb-ingest-documents-tool` | Submit documents and return a browser approval link. | | `kb-import-status-tool` | Poll import progress and retrieve indexed document IDs. | Search and document tools have no tenant or project argument. Every request rechecks account activity, membership in the selected project, current client policy, token audience, expiry and revocation. Reading a document by its numeric ID cannot escape the selected project. Existing document access scopes apply. The PHP surface is `ConnectedProjectWorkspace` / `McpDocumentImportService`. The REST adapters are `POST /mcp/knowledge/{connection}/api/info`, `/search`, `/document` and `/imports`; they use the same OAuth authority and services. ## Send documents from Codex Ask Codex to import specific local files. It can send Markdown and plain text as text, or PDF/DOCX bytes as base64. One call accepts at most ten files, 5 MB per decoded file and 10 MB total. File signatures are checked. Arbitrary filesystem paths and download URLs are not accepted as file content. 1. Codex submits the files to `kb-ingest-documents-tool`. 2. AskMyDocs stages them and returns the import ID, file manifest and `approval_url`. The files have not been indexed yet. 3. Open that link. Review the destination, names, sizes and text previews, then approve indexing. The MCP token cannot approve the operation itself. 4. Codex polls `kb-import-status-tool`. Only `ready: true` means every file was indexed successfully and can be used for retrieval. The import capability requires `mcp:ingest` plus the existing admin/super-admin ingestion role and unrestricted membership in the selected project. Read-only connections use `mcp:read`. Uploads use a separate content-addressed source namespace, preserving existing source files. Identical retries return the original import, including concurrent submissions. Approval is valid for one hour and is bound to the staged byte hashes; changed staged files are rejected. The queue rechecks the initiating user's current permissions before processing. The import delegates to `KbUploadStagingService` and `IngestDocumentJob`, the same conversion, chunking, PII handling, embedding and persistence pipeline used by existing uploads. It does not implement a second document index. ## Authentication and deployment Protected-resource discovery is available at `/.well-known/oauth-protected-resource/mcp/knowledge/{connection}`. An unauthenticated MCP request returns a `WWW-Authenticate` challenge pointing at that exact resource metadata. The MCP authorization-server issuer is `APP_URL/oauth/mcp`, discovered at `/.well-known/oauth-authorization-server/oauth/mcp`. The existing authorization server provides public-client dynamic registration, authorization codes with mandatory S256 PKCE, issuer-bound callbacks, resource audience validation and refresh-token rotation. Access tokens last at most one hour (or the shorter Sanctum lifetime). Refresh families expire 90 days after consent; replaying a consumed refresh token revokes its family. Browser approval and connection management require a session and CSRF protection. The legacy `/mcp/kb` tenant-token endpoint and the existing API OAuth clients keep their separate authentication contracts. Deploy the migration and frontend build: ```bash theme={null} php artisan migrate npm run build ``` `laravel/mcp` is a production dependency. Use the installation's public HTTPS `APP_URL`, keep its queue worker running, and use a shared lock-capable cache store across workers. Dynamic registration and MCP traffic have independent rate limits. Tokens are hashed at rest; tool audit records omit document bodies and secrets. Revocation is available at `/oauth/connections`. See OpenAI's [MCP authentication](https://developers.openai.com/plugins/build/auth) and [plugin packaging](https://developers.openai.com/plugins/build/plugins) guides for client installation and public distribution. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.